[BUG] Custom project-level agents are non-discoverable

Resolved 💬 2 comments Opened Apr 1, 2026 by GregoryArmstrong Closed Apr 20, 2026

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

  1. 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.

  1. Also tried placing the same file in ~/.claude/agents/ (user-level)
  2. Restart the Claude Code session
  3. Run claude agents from the terminal — only 5 built-in agents are listed
  4. Run /agents inside a session — no custom agents shown
  5. Try @"test-agent" — not recognized
  6. 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

View original on GitHub ↗

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