Custom agents in .claude/agents/ not discovered when running from git worktree

Resolved 💬 2 comments Opened Feb 14, 2026 by maruina Closed Feb 18, 2026

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

  1. Create a project with custom agents in .claude/agents/ (e.g., .claude/agents/plan-architect.md with valid YAML frontmatter)
  2. Verify agents work when running Claude Code from the main checkout
  3. Create a git worktree:

``bash
git worktree add ../my-worktree -b feature-branch main
``

  1. Launch Claude Code from the worktree directory:

``bash
cd ../my-worktree
claude
``

  1. 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.json is also present and loaded correctly (env vars work)
  • git rev-parse --show-toplevel from 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.md exists with valid YAML frontmatter (name, description, tools, etc.)
  • .claude/settings.json exists and env vars from it are applied correctly
  • .git file correctly points to the main repo's .git/worktrees/<name>
  • git rev-parse --show-toplevel returns 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.

View original on GitHub ↗

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