The plan was clean. I’d built a board of agents: a CFO, a CMO, an analytics one I named Echo. Each one lives in its own directory under projects/mission-control/agents/. Each directory has a CLAUDE.md that defines role, personality, context. Talk to the CFO, you’re in the CFO’s environment. The interface was supposed to feel like reaching a specific person.
The command I expected: claude --agent cfo. The flag exists. I’d seen it in the docs. I typed it and got default Claude, starting blank in my home directory, knowing nothing about the board.
No error. No “agent cfo not found.” Just Claude, ready and unhelpful.
The problem is that --agent in Claude Code already means something. It routes to built-in subagents: Plan, Explore, general-purpose, that crew. There’s no cfo registered in that system. When Claude Code doesn’t recognize the agent name, it doesn’t fail. It quietly starts anyway.
Which means if you build your mental model around claude --agent cfo summoning your CFO, you can use it for weeks before noticing the CFO never showed up. The session looks like a Claude session. It responds. You might not catch that it’s running without the CFO’s CLAUDE.md unless you’re paying close attention to the persona.
I caught it fast. But fast was still one session before I realized.
The fix was a wrapper function in ~/.zshrc. About 20 lines. It intercepts claude --agent <name>, checks whether projects/mission-control/agents/<name>/ exists as a directory. If it does, it spawns a subshell that cd’s there first, so Claude picks up the local CLAUDE.md as project context. If the name isn’t in the agents directory, the flag passes through to the real binary unchanged, so the built-in subagents still work.
Now claude --agent cfo routes to the CFO’s environment. claude --agent plan routes to the built-in Plan subagent. Two definitions of “agent,” coexisting without conflict. Adding a new board member means creating a directory. The wrapper picks it up automatically, no edits needed.
What bothers me more than the initial confusion is the silent fallthrough. No crash. No log entry. Just Claude, starting without context, answering questions competently in a way that sounds right but isn’t the right voice.
Silent failures in AI systems are worse than hard failures for exactly this reason. A crash you can debug. A session that starts with the wrong context but still produces useful-sounding output, that lives invisibly until something feels off enough to make you look. And noticing requires being suspicious of something that appears to be working.
The wrapper makes the failure loud. If the name doesn’t map to a known agent directory and it’s not a built-in subagent, you know what you’re getting. Predictable fallback, not silent drift.
Build the wrapper before you spend a month talking to someone who was never in the room.