Claude Code Field Guide
26 / 35

Agent Teams

Named teammates that talk to each other directly and share a task list — solving the bottleneck of everything routing through one main agent.

Needs correction
Currency check: The video presents this as a straightforward, ready-to-use feature. In fact it's explicitly experimental and disabled by default — an important correction.

Sub agents report only back to the main agent — with several of them, that main agent becomes a bottleneck, and sub agents can't see each other's findings directly. Agent teams solve this: teammates communicate with each other directly and share a task list, instead of everything flowing through one hub. The video's framing — spin up a researcher, a writer, and a reviewer that talk to each other — is directionally correct.

Important correction: as of current documentation, agent teams are explicitly labeled experimental and are disabled by default. You have to opt in by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your settings or environment before Claude will ever propose or spawn a team. There are known limitations: no session resumption for in-process teammates after /resume, task status can lag, and there's exactly one team per session with no nesting. Also worth knowing: agent teams use roughly 7x more tokens than a standard session when teammates run in plan mode — this is a genuinely expensive feature, not a free upgrade over subagents. Use it for research, review, and debugging-with-competing-hypotheses tasks where parallel, adversarial exploration adds real value; for sequential or same-file work, a single session or ordinary subagents are more effective and far cheaper.

Debugging with competing hypotheses

Facing an intermittent bug with no obvious cause, a developer spawns five teammates to each investigate a different hypothesis and explicitly argue against each other's theories — the surviving explanation after the debate is far more likely to be the real root cause than a single agent's first plausible guess.

A three-lens PR review

One teammate reviews a PR for security, one for performance, one for test coverage — and because they share a task list and can message each other, the lead agent gets a synthesized, cross-checked review rather than three siloed reports it has to reconcile itself.