Agent and Command Discovery Issue

[amykhar]

There seems to be an issue with discovering the agents and commands that are in my project directories. It's rather strange, but if the agents and commands are in the project .claude/agents/agent-os directory, they are not found.

• If I rename the directory to something else other than agent-os, they are discovered. (example: change the directory name to os. It works. Change it to agent-turtle. It works)
• If I put them in my ~/.claude/agents/agent-os directory, they work.

I'm sure it's a claude bug and not yours, but I thought creating an issue here would help others find it.
I have installed multiple times, deleted by ~/.claude directory as well as my .claude.json file too.

claude version: 2.0.25 (Claude Code)
os: macOs 15.7.1 (24G231)
iterm2 for my terminal

[ssr1ram]

Check your .gitignore file, I've seen it happen where it does not recognize commands if there is a conflict with something in .gitignore

[amykhar]

Wow. That's something I would never have expected. Thank you so much!

[saschabratton]

@amykhar (and anyone else looking to understand the issue.)

Claude ignores files that are gitignored. There is a feature request around the issues this can create. (See: anthropics/claude-code#5105)

There is a new update (v2.0.27 as of a day or two ago) that creates a /config option that allows gitignored files to be shown in claude's @ file picker; however, this does not change the functionality that claude will ignore commands in a subdirectory that is gitignored.

If you want to ignore the agent-os directory for a project, but still want to access agent-os commands in claude, you can add this to .gitignore:

/agent-os/

If you're project is structured something like:

.
├── agent-os
│   ├── config.yml
│   ├── product
│   └── standards
├── .claude
│   ├── commands
│   │   ├── agent-os

The problem you described occurs, when you do something like:

agent-os/

Then the agent-os/ ignore would include both ./agent-os and ./.claude/commands/agent-os; whereas, a /agent-os/ ignore includes only the project root-level ./agent-os.