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
- Have 5 custom agent
.mdfiles in~/.claude/agents/with valid YAML frontmatter (name, description, model, color, memory fields) - Reinstall Claude Code:
sudo rm -rf /opt/homebrew/lib/node_modules/@anthropic-ai/claude-code && npm install -g @anthropic-ai/claude-code - Run
claude agentsfrom CLI — shows only 5 built-in agents, no custom agents - Open
/agentsdialog inside Claude Code — shows "No agents found" - 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,memoryfields) - File permissions are
-rw-r--r--@(644) - Files have very long lines in the
descriptionfield (1600-2500+ chars) with escaped newlines — this may be relevant to parsing - After reinstall, the vendored ripgrep binary at
vendor/ripgrep/arm64-darwin/rghad an EACCES permission error (fixed withchmod +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
---This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗