In the post on Claude Code agents, the model was delegation: a subagent gets a task, works in its own context window, and hands back a summary. One direction, one report, done. That covers a surprising amount of ground, but it has a ceiling. Subagents can’t talk to each other. If two investigators need to compare notes, everything has to route through the main conversation, and the main conversation becomes the bottleneck you built subagents to avoid.
Agent teams are the experimental next step: instead of spawning workers inside your session, you spawn teammates, each one a full, independent Claude Code session with its own context window. One session acts as the team lead; teammates share a task list, claim work off it (with file locking so two agents can’t grab the same task), and message each other directly through a mailbox system. Discussion happens between agents, not through you.
The official comparison is blunt about the trade: subagents are for “focused tasks where only the result matters” at lower token cost; agent teams are for “complex work requiring discussion and collaboration”. Every teammate is a separate Claude instance on the meter.
Agent teams are experimental and off by default. Enable with an environment variable, either in your shell or in settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}That’s the whole setup. Since v2.1.178 there’s no create-a-team ceremony: every session has one implicit team, and Claude spawns teammates directly through the Agent tool when you ask. (Earlier versions had explicit TeamCreate/TeamDelete tools; they’re gone.)
By default teammates run in-process, inside your current terminal, visible through the agent panel (arrow keys to select a teammate, Enter to open its transcript and message it directly, x to stop one, Ctrl+T for the shared task list). If you live in tmux or iTerm2, set teammateMode to "tmux" or "iterm2" and each teammate gets its own split pane, which turns your terminal into a small mission control.
No new syntax. You describe the team you want:
Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverageThe patterns from the docs that work well map to how you’d actually staff humans:
Parallel review is the example above. Reviews are read-heavy and independent, which makes them the ideal first workload.
Competing hypotheses is my favorite, because it uses inter-agent messaging for something subagents genuinely can’t do:
Spawn 5 teammates to investigate different hypotheses about this bug.
Have them talk to each other to try to disprove each other's theories,
like a scientific debate.Plan-gated implementation gives you a teammate that must get sign-off before touching anything:
Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.The teammate stays read-only in plan mode until the lead approves its plan. The lead handles approval autonomously, against criteria you set.
Teammates can use your custom agent definitions too ("spawn a teammate using the security-reviewer agent type"), picking up that agent’s system prompt, tool restrictions, and model. One wrinkle worth knowing: a teammate loads CLAUDE.md, MCP servers, and skills like any fresh session, but it does not inherit your conversation history. Whatever context the task needs must go in the spawn prompt. It’s the same discipline as briefing subagents, just more so.
Because teammates work autonomously, the interesting control question is how work gets accepted. The answer is hooks. Three events fire during team operation (TaskCreated, TaskCompleted, and TeammateIdle), and a hook that exits with code 2 blocks the action and sends feedback. A TaskCompleted hook that runs the test suite and rejects the completion on failure means a teammate literally cannot mark its task done with red tests. It’s the same philosophy as Superpowers: don’t ask the model to be disciplined, make the workflow enforce it.
This is the part to read twice. Per Anthropic’s own docs, agent teams use roughly 7x more tokens than a standard session when teammates run in plan mode. The mitigation guidance:
/config). Sonnet teammates coordinated by an Opus-class lead is the intended shape.The documented limitations are real and worth internalizing before you commit a workflow to teams:
isolation: worktree), teammates share your working tree. Partition work so each teammate owns different files, or they will clobber each other./resume. Session resumption and rewind don’t cover them.There’s also a quietly important security property: messages between agents carry no user authority. A teammate can’t approve another agent’s permission prompts, and permission requests bubble up to the lead. No agent can talk another agent into privileges you didn’t grant.
The upper bound got a public stress test: Anthropic’s engineering team ran 16 agents in parallel (about 2,000 Claude Code sessions over two weeks, 2 billion input tokens, just under $20,000) and produced a 100,000-line Rust C compiler capable of building Linux 6.9 on x86, ARM, and RISC-V. No central orchestrator; agents claimed tasks off a shared directory with file locking, structurally the same decentralized pattern teams use.
Their top lesson transfers directly to small teams: write extremely high-quality tests. Autonomous agents optimize against whatever acceptance signal exists. If the tests are weak, sixteen agents will build the wrong thing sixteen times faster.
My working heuristic, an extension of the one from the subagents post:
The progression across these three posts is a shrinking of your role in the loop, on purpose: from doing the work, to delegating the work, to staffing the room where the work gets discussed. At 7x the tokens, agent teams are not the default. They’re the tool for problems where the discussion itself was the thing you couldn’t previously buy.