[BUG] Custom project-level agents are non-discoverable
Preflight Checklist
- [x] I have searched existing issues and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code
What's Wrong?
- v2.1.89, macOS
- Custom agents in .claude/agents/ (project-level) are not discovered
- claude agents only shows 5 built-in agents
- Even a minimal test agent with just name and description frontmatter doesn't load
- /agents dialog shows nothing custom
- @ typeahead doesn't show custom agents
What Should Happen?
Should have project-level agents .md files discoverable
Error Messages/Logs
Steps to Reproduce
- Create a project-level .claude/agents/ directory with a minimal agent file:
---
name: test-agent
description: A simple test agent
---
You are a test agent.
- Also tried placing the same file in ~/.claude/agents/ (user-level)
- Restart the Claude Code session
- Run claude agents from the terminal — only 5 built-in agents are listed
- Run /agents inside a session — no custom agents shown
- Try @"test-agent" — not recognized
- Try invoking via the Agent tool with subagent_type: "test-agent" — returns "Agent type not found"
Claude Model
Opus
Is this a regression?
Yes, this worked in a previous version
Last Working Version
2.1.87
Claude Code Version
2.1.89
Platform
Anthropic API
Operating System
macOS
Terminal/Shell
Terminal.app (macOS)
Additional Information
Additional context:
- v2.1.89, macOS Darwin 25.2.0
- Agent files have valid YAML frontmatter with name and description fields
- Files are UTF-8 with nonzero inodes (not a NFS/FUSE zero-inode issue)
- File permissions are standard (644 for files, 755 for directory)
- Also tested with more complex agents that have model, color, and memory frontmatter fields — same result
- claude agents --setting-sources user, --setting-sources project, and --setting-sources local all show only built-in agents
- Even claude --agents '{"test": {"description": "Test", "prompt": "Hello"}}' followed by claude agents does not show the inline agent
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗