Somebody on r/ClaudeCode titled a thread “Convince me that agent teams are not pointless.” Google puts it in the top five for the feature’s own name, one slot below Anthropic’s documentation.
That is the right question, and most of the answers to it are bad because they answer a different one. The common defense is that teams do more work at once. Parallelism is the least interesting thing agent teams give you, and it is the part most likely to lose you money.
What actually changes is the return path
A subagent runs inside your session and hands its final summary back to the caller. The main agent manages all the work, and every result flows through one context.
A teammate is a separate Claude Code instance. It loads project context the way a normal session does, CLAUDE.md and MCP servers and skills included, but it does not inherit the lead’s conversation history. It gets a spawn prompt and then it is on its own. Teammates message each other directly by name, through a mailbox that is a JSON file on disk at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json, and they coordinate through a shared task list where tasks can declare dependencies and claiming uses file locking to survive two teammates reaching for the same work.
The lead stops being a router. That is the actual change, and everything else follows from it.
| One session | Subagents | Agent teams | |
|---|---|---|---|
| Context | One window, everything in it | Own window, summary returns | Own window, fully independent |
| Who coordinates | You | The main agent | The team members, through messages |
| Communication | None needed | Result to the caller | Any teammate to any teammate |
| You can talk to | The session | Nothing mid-flight | Any teammate directly |
| Token cost | Baseline | Lower, results summarized back | Higher, each is a full instance |
| Fails when | Context fills | The briefing was vague | Two teammates touch one file |
| Buys you | Continuity | Context isolation | Independent judgment |
Read down the last row. Continuity, isolation, and judgment are three different purchases, and only the third one needs several models running at once.
The strongest documented case is an argument
The Claude Code documentation lists use cases for teams, and the one that earns the cost is not the tidy division of labour. It is the debugging example, where the instruction is to spawn teammates to investigate different hypotheses and “have them talk to each other to try to disprove each other’s theories, like a scientific debate.”
The stated reason is worth quoting, because it is a claim about a failure mode rather than about speed:
Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it.
A single agent finds one plausible explanation and stops looking. That is not a capability problem you can fix with a better model or a longer context window, because the model is behaving reasonably: it found something that fits. What breaks the anchor is a second investigator who did not watch the first one work and who is rewarded for disagreeing.
Parallel review works for the same reason. A single reviewer gravitates toward one class of issue at a time, so splitting review into a security lens, a performance lens, and a test-coverage lens gets each one full attention. The teammates are not faster than one reviewer doing three passes. They are less correlated than one reviewer doing three passes, which is the thing that was actually missing.
This is the same argument as putting a rival lab’s model in the reviewer seat. Independent judgment comes from decorrelated failure surfaces, and you get those by construction: different context, different lens, different instructions, no shared conversation to anchor on.
Parallel implementation is the weak case
The pitch that sells the feature is four teammates building four modules at once. It is the use case most likely to disappoint.
The documentation is unusually direct about this. Overwrites are what happens when two teammates edit the same file, so the work has to be split so each teammate owns a different set of files. That constraint is doing a lot of work, because it means the architecture has to already be separable before the team helps. If your codebase has clean module boundaries, you have a team-shaped task. If it does not, you have a merge conflict generator, and the agents will not tell you which one you have until afterwards.
The experimental limitations land hardest here too. Task status can lag when a teammate fails to mark work complete, which blocks everything that depended on it. In-process teammates do not survive /resume or /rewind, and the lead may then try to message teammates that no longer exist. The lead can also decide the team is finished while tasks remain open.
None of that is fatal for a review or a research sweep, where the deliverable is findings and a stalled task is visible immediately. All of it is expensive in the middle of a refactor.
The hooks are the part worth building on
Buried in the feature is the piece that matters most for anyone building a real pipeline. Teams expose three hooks, and each one can refuse:
TeammateIdleruns when a teammate is about to go idle. Exit with code 2 and it keeps working.TaskCreatedruns when a task is being created. Exit with code 2 and the task is not created.TaskCompletedruns when a task is being marked complete. Exit with code 2 and it is not marked complete.
Exit code 2 sends feedback back to the agent along with the refusal. That is a gate you control with a shell script, sitting on the boundary where an agent tries to declare itself finished.
teammate: "done"
│
▼
┌─────────────────────┐
│ TaskCompleted hook │
│ tests? lint? diff? │
└────┬───────────┬────┘
│ │
exit 0 exit 2
│ │
▼ └──────────┐
task closes │
feedback returns,
task stays open,
teammate keeps working
│
└──► back to workThe declaration of completion is the moment worth intercepting, because a model marking its own task complete is the same self-approval problem as a model reviewing its own code. An agent that can close its own tasks will close them.
That is why I keep coming back to the framing that these pipelines are gates rather than factories. Every part of agent teams that produces reliability is a refusal: the reviewer that cannot write, the hook that will not let a task close, the plan approval a teammate has to get from the lead before it may leave read-only mode. The parts that produce volume are the parts that produce the merge conflicts.
The number is small, and it stays small
The guidance is to start with 3 to 5 teammates, with a line that reads like it came from watching people: “Three focused teammates often outperform five scattered ones.” Even with 15 independent tasks available, 3 teammates is the suggested starting point, at roughly 5 to 6 tasks each.
Token costs scale linearly with teammates, coordination overhead grows, and the returns diminish. The interesting part is that the ceiling is not really about cost. Coordination overhead means every added teammate makes the others’ job harder, so the curve turns down before your invoice does.
@undefinedKi wrote one of the most-shared explainers when the feature landed in June, and the practical rules in it converge on the same place: keep it to three to five agents, give each one its own files, define exact outputs, name who talks to whom. That post puts the cost at three to four times a single session, which is a practitioner’s estimate rather than a documented figure, and it matches the documented direction if not the precision.
The right instinct is that the team size is a budget for disagreement. You are paying for independent opinions, and you need enough of them to break an anchor and few enough that they can still reach one answer.
The flag does more than turn a feature on
Enabling agent teams changes ordinary delegation, which is the kind of side effect that produces a confusing afternoon.
While teams are enabled, Claude names subagents on its own so it can message them later, and a subagent that Claude names launches as a teammate. Teams can therefore form during work you never framed as team work. The two report back differently: Claude receives a subagent’s result when it completes, while a teammate’s idle notification says only that it stopped and does not carry its output. An orchestration flow written to wait on subagent results can stall against that.
The switch back is CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS set to 0, and it applies without restarting the session. Non-interactive runs with -p, including Agent SDK sessions, never spawn teammates at all, so anything you automate in CI behaves differently from what you tested by hand.
Buy disagreement, not throughput
The skeptical thread had it almost right. Agent teams are pointless for most of what people reach for them to do, and the reaching is encouraged by a pitch about parallel work.
They stop being pointless at the moment you want two agents to reach different conclusions and defend them. Debugging where the cause is genuinely unknown, review that needs several lenses at once, design exploration where an adversarial voice is the point: those are worth several sessions running at once, because a single session was never going to produce the disagreement no matter how long you let it run.
Ask what you would do with a second opinion before you spawn a team. If the answer is that you would merge it into the first one without reading it, you wanted a subagent.
