Custom agents in ~/.claude/agents/ not detected after reinstall

Resolved 💬 3 comments Opened Mar 31, 2026 by abe-thoughtful Closed Apr 3, 2026

Bug Description

Custom agent .md files in ~/.claude/agents/ are not detected by Claude Code after a clean reinstall. The /agents dialog shows "No agents found" even though the files exist and have valid frontmatter.

Steps to Reproduce

  1. Have 5 custom agent .md files in ~/.claude/agents/ with valid YAML frontmatter (name, description, model, color, memory fields)
  2. Reinstall Claude Code: sudo rm -rf /opt/homebrew/lib/node_modules/@anthropic-ai/claude-code && npm install -g @anthropic-ai/claude-code
  3. Run claude agents from CLI — shows only 5 built-in agents, no custom agents
  4. Open /agents dialog inside Claude Code — shows "No agents found"
  5. Copying the same files to project-level .claude/agents/ also does not resolve the issue

Expected Behavior

Custom agents in ~/.claude/agents/ (and project-level .claude/agents/) should appear in the /agents dialog and claude agents output.

Actual Behavior

Only built-in agents are shown. Custom agent files are completely ignored despite being valid .md files with proper frontmatter.

Environment

  • OS: macOS (Darwin 25.4.0, arm64)
  • Shell: zsh
  • Install method: npm install -g @anthropic-ai/claude-code
  • Node package location: /opt/homebrew/lib/node_modules/@anthropic-ai/claude-code

Additional Context

  • Agent files are UTF-8 text with valid YAML frontmatter (name, description, model, color, memory fields)
  • File permissions are -rw-r--r--@ (644)
  • Files have very long lines in the description field (1600-2500+ chars) with escaped newlines — this may be relevant to parsing
  • After reinstall, the vendored ripgrep binary at vendor/ripgrep/arm64-darwin/rg had an EACCES permission error (fixed with chmod +x), which may indicate broader permission issues from the install

Agent File Frontmatter Example

---
name: code-arch-reviewer
description: "Use this agent when you need a comprehensive, autonomous code and architecture review..."
model: opus
color: orange
memory: user
---

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗