Custom agents in .claude/agents/ not discovered when running from git worktree
Bug Description
Custom agents defined in .claude/agents/ are not discovered when Claude Code is launched from a git worktree directory. The Task tool fails with Agent type '<name>' not found, listing only built-in and plugin agents.
Reproduction Steps
- Create a project with custom agents in
.claude/agents/(e.g.,.claude/agents/plan-architect.mdwith valid YAML frontmatter) - Verify agents work when running Claude Code from the main checkout
- Create a git worktree:
``bash``
git worktree add ../my-worktree -b feature-branch main
- Launch Claude Code from the worktree directory:
``bash``
cd ../my-worktree
claude
- Attempt to use a custom agent via the Task tool
Expected Behavior
Custom agents should be discovered and available, since:
.claude/agents/is checked into git and present in the worktree checkout.claude/settings.jsonis also present and loaded correctly (env vars work)git rev-parse --show-toplevelfrom the worktree returns the worktree root, where.claude/agents/exists
Actual Behavior
Error: Agent type 'plan-architect' not found. Available agents: Bash, general-purpose,
statusline-setup, Explore, Plan, claude-code-guide, ...
Only built-in and plugin agents are listed. No project-level custom agents appear.
Environment
- OS: macOS (Darwin 24.6.0)
- Claude Code model: claude-opus-4-6
- Git version: standard macOS git
- Worktree structure:
````
/path/to/repo/ # main checkout — agents work here
/path/to/worktrees/feature/ # git worktree — agents NOT found
Verification
Confirmed the following in the worktree:
.claude/agents/plan-architect.mdexists with valid YAML frontmatter (name,description,tools, etc.).claude/settings.jsonexists and env vars from it are applied correctly.gitfile correctly points to the main repo's.git/worktrees/<name>git rev-parse --show-toplevelreturns the worktree root
Notes
This may be related to how Claude Code resolves the project root for agent/command discovery. The .claude/settings.json env vars load fine from the worktree, so it's specifically agent (and possibly command) discovery that's affected.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗