Claude Code agent teams let one Claude Code session act as a team lead that spawns several teammates, each a separate Claude Code instance with its own context window. Teammates share a task list, message each other by name, and you can talk to any of them directly. Subagents, by contrast, only report a result back to the session that started them.
Agent teams are still experimental and off by default in Claude Code 2.1.322, the latest release on 10 November 2026. You turn them on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. They cost more than a single session: Anthropic puts it at about 7x the tokens when teammates run in plan mode, and the worked review below comes to 2.3x the cost of one session on Opus 5.5. They pay off for parallel review, research and debugging, and rarely for ordinary feature work.
What Claude Code agent teams are
A team has four parts, per the agent teams docs:
| Part | What it is |
|---|---|
| Team lead | Your main session. It spawns teammates, assigns work and merges results, and stays lead for life. |
| Teammates | Separate Claude Code instances. Each loads CLAUDE.md, MCP servers and skills plus the lead's spawn prompt, but not the lead's conversation history. |
| Task list | Shared work items with three states (pending, in progress, completed) and dependencies. Teammates claim tasks with file locking so two can't take the same one. |
| Mailbox | One JSON inbox per agent at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. A teammate that finishes sends the lead its final answer. |
You don't create a team by hand. Since version 2.1.178 (15 June 2026), every session with the flag on has one implicit team named session- plus the first eight characters of the session ID. Claude starts a teammate whenever it calls the Agent tool with a name, and Claude Code doesn't ask you to confirm. Older guides that mention TeamCreate and TeamDelete describe tools that no longer exist.
Agent teams vs subagents
A subagent does a side task in its own context and hands a summary back. A teammate keeps running, messages the other teammates and the lead, and you can open its transcript and redirect it.

| Subagents | Agent teams | Dynamic workflows | |
|---|---|---|---|
| Status | On by default | Experimental, off by default | On for paid plans (Pro turns it on in /config) |
| Who holds the plan | Main session, turn by turn | Lead session, turn by turn | A script Claude writes |
| Workers message each other | Only subagents Claude named | Yes, directly by name | No, the script passes results |
| Shared task list | No | Yes, when the model has the Task tools | No, results live in script variables |
| Typical size | A few per turn | 3 to 5 long-running peers | Dozens to hundreds, up to 1,000 agents a run |
| You can message a worker | No | Yes | No |
| If you interrupt | Restarts the turn | Teammates keep running | Resumable in the same session |
| Token cost | Lower: summaries come back | Highest: about 7x in plan mode | Warns past 25 agents or 1.5M projected tokens |
Anthropic's subagents and workflows docs say to try the lighter option first: subagents when only the result matters, a dynamic workflow when one pattern repeats across hundreds of files, and a team when workers need to share findings and argue.
One gap catches people: agent teams don't put teammates in separate git worktrees. Two teammates editing the same file overwrite each other, so split the work by file ownership. Subagents and /batch can each get their own worktree.
How to enable agent teams
Add the flag to the env block of ~/.claude/settings.json (or a project's .claude/settings.json), or export it in your shell:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Then check four things before you ask for a team.
- Run
claude update. Many team fixes landed in October and November; this post checked 2.1.322. New to Claude Code? See the install guide. - Use an interactive session. With
claude -por the Agent SDK, Claude never spawns teammates, and a named subagent runs as an ordinary subagent even with the flag on. - Decide whether you want the shared task list. Since 2.1.233 (14 August 2026) the Task tools are off by default on newer models, and the tools reference lists them as default only on Opus 4.7, Sonnet 4.6, Haiku 4.5 and earlier. On Opus 5.5 or Sonnet 5.5, teammates coordinate by message unless you start Claude Code with
CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude. - Pick a display mode. The default,
in-process, runs every teammate inside your terminal and works anywhere. Split panes give each teammate its own pane and need tmux, or iTerm2 with theit2CLI. They don't work in VS Code's integrated terminal, Windows Terminal or Ghostty.
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
},
"teammateMode": "auto"
}
auto uses split panes inside tmux or in iTerm2 with it2, and in-process otherwise. For one session, use claude --teammate-mode auto (experimental, not listed in claude --help).
Turning the flag on changes ordinary delegation too. Claude sometimes names subagents on its own so it can message them later, and with the flag on, every named subagent launches as a teammate. Teams can form when you didn't ask for one. To go back, set the variable to "0" in settings; Claude Code rereads it each time it spawns, so no restart is needed.
Are agent teams still experimental?
Yes. The docs open with "Agent teams are experimental and disabled by default", and the run agents in parallel page lists them the same way. The feature launched as a research preview alongside Opus 4.6 on 5 February 2026, labeled in the changelog as a "token-intensive feature". Nine months later, at 2.1.322, the flag is still required.

| Date | Version | Change |
|---|---|---|
| 5 Feb 2026 | 2.1.32 | Research preview ships with Opus 4.6, behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 |
| 6 Feb 2026 | 2.1.33 | TeammateIdle and TaskCompleted hooks |
| 5 Mar 2026 | 2.1.69 | Teammates can no longer spawn nested teammates |
| 15 Jun 2026 | 2.1.178 | TeamCreate and TeamDelete removed; one implicit team per session |
| 14 Aug 2026 | 2.1.233 | Task tools off by default on Opus 4.8, Sonnet 5, Fable 5 and newer |
| 17 Aug 2026 | 2.1.234 | "Default teammate model" setting removed; teammates use the lead's model |
| 19 Oct 2026 | 2.1.304 | Approving a shutdown request no longer exits the whole CLI |
| 10 Nov 2026 | 2.1.322 | Latest release; still experimental |
The documented limitations in 2.1.322:
/resumeand/rewinddon't bring back in-process teammates. After a resume the lead may message teammates that no longer exist, so tell it to spawn new ones.- Teammates sometimes fail to mark a task complete, which blocks the tasks that depend on it.
- A session has exactly one team, only the lead can manage it, and you can't hand leadership to a teammate.
- Teammates start in the lead's permission mode, including
bypassPermissionsif you launched with--dangerously-skip-permissions. You can't give a teammate its own mode at spawn time.
A worked example: a parallel PR review
Anthropic suggests starting with review and research, where nothing gets written and file conflicts can't happen. Here is a three-reviewer team for a pull request, with a gate that stops a reviewer from going idle before it has written its findings.
First, the gate. A TeammateIdle hook runs each time a teammate is about to stop; exit code 2 sends the stderr message back as feedback and keeps it working. The hooks guide covers the event list in full. Save this as .claude/hooks/review-written.sh and make it executable:
#!/bin/bash
# Keep a reviewer working until its findings file exists and is not empty.
NAME=$(jq -r '.teammate_name')
FILE="review/${NAME}.md"
if [ ! -s "$FILE" ]; then
echo "Write your findings to $FILE before going idle." >&2
exit 2
fi
exit 0
Register it in .claude/settings.json. TeammateIdle takes no matcher:
{
"hooks": {
"TeammateIdle": [
{ "hooks": [{ "type": "command", "command": ".claude/hooks/review-written.sh" }] }
]
}
}
Then give the lead names, a lens per reviewer, the files and an output path:
Create an agent team to review PR 214 (branch feat/session-refresh).
Spawn three teammates on Sonnet, named security, perf and tests.
- security: token handling, session expiry and input validation in src/auth/.
- perf: database queries and caching in src/api/sessions.ts.
- tests: whether the new paths in src/auth/ have tests, and what is missing.
Each writes findings with a severity to review/<name>.md and nothing else.
When all three are done, have them challenge each other's top two findings,
then write one summary to review/summary.md.
What happens next:
- The lead spawns
security,perfandtests. They appear in the agent panel below your prompt. Up and Down select one, Enter opens its transcript, and typing sends it a message. - Each teammate reads its files and writes its report. One that tries to stop without a report gets pushed back by the hook.
- Each idle notification carries the teammate's final answer to the lead. If the lead starts doing the review itself, tell it: "Wait for your teammates to complete their tasks before proceeding."
- In the challenge round,
perfmessagessecuritydirectly to dispute a finding, with its own reasoning still in context. - When the summary is written, tell the lead to shut the teammates down. Each active teammate keeps using tokens until it exits.
Teammates' permission prompts appear in the lead's session, so pre-approve the read-only commands they need first.
What agent teams cost
Every teammate is a full Claude Code session, so a team pays for each one's context on every request. The costs page says agent teams "use approximately 7x more tokens than standard sessions when teammates run in plan mode", and that usage is roughly proportional to team size.
Here is the review above, modeled three ways at Anthropic's API list prices on 10 November 2026 (Opus 5.5: $4 / $20 per million tokens input / output, $0.20 cache reads, $5 five-minute cache writes; Sonnet 5.5: $2 / $10, $0.10, $2.50).
Assumptions: every agent starts with 20,000 tokens of context (system prompt, tools, CLAUDE.md), produces 800 output tokens per request, and its context grows steadily. Each request reads the previous context from cache and writes only the new part. A single session does the review in 60 requests, growing to 140,000 tokens. With subagents, the main session runs 15 requests and each of three subagents 30, growing to 100,000. In the team, the lead runs 25 requests and each teammate 40 (review, messages, challenge round), growing to 110,000.

| Setup | Requests | Tokens processed | Cost | Against one Opus session |
|---|---|---|---|---|
| Single session, Sonnet 5.5 | 60 | 4.85M | $1.18 | 0.5x |
| Single session, Opus 5.5 | 60 | 4.85M | $2.37 | 1x |
| Main + 3 subagents, Opus 5.5 | 105 | 6.01M | $4.16 | 1.8x |
| Lead Opus 5.5 + 3 teammates on Sonnet 5.5 | 145 | 9.04M | $3.18 | 1.3x |
| Lead + 3 teammates, all Opus 5.5 | 145 | 9.04M | $5.48 | 2.3x |
Over 20 reviews a month: $47.31 for one Opus session, $109.67 for an all-Opus team, $63.52 with Sonnet teammates. To price your own sessions, put their token counts into the token cost calculator. Note the team's extra cost is mostly extra work (145 requests against 60), each re-reading its own context.
Three things drive the bill up faster than this example shows:
- Cache expiry. An in-process teammate's prompt cache lasts five minutes by default, even on a Claude subscription where the main conversation gets an hour. A teammate that idles longer and is then woken re-writes its whole context: for 110,000 tokens on Opus 5.5 that is $0.55, against $0.022 to read it from cache. If teammates sit idle between turns, set
subagentPromptCacheTtlto1h; one-hour writes cost $8 instead of $5 on Opus 5.5, so it pays once a teammate would otherwise miss the cache. - Plan mode. Anthropic's 7x figure is for teammates in plan mode, where each one explores and plans in its own context before writing code.
- Coordination chatter. A GitHub issue open since April reports the lead spending 13% to 22% of its input tokens acknowledging idle notifications.
On a Pro, Max or Ultra plan none of this shows up as dollars. It comes out of the shared five-hour and weekly limits, and a team draws on them in proportion to the tokens all its members process. The Claude Code pricing guide has the plan limits and a month of API use worked out.
For scale at the far end, Anthropic researcher Nicholas Carlini had 16 Claude agents write a 100,000-line C compiler in Rust over about 2,000 Claude Code sessions in two weeks. That came to 2 billion input tokens, 140 million output tokens and "a total cost just under $20,000". It ran on a custom harness (a loop of claude -p in Docker containers sharing a git repository, with lock files to claim tasks), not on the agent teams feature, but it shows what parallel Claude work costs once it runs unattended.
How to keep agent team costs down
- Run teammates on Sonnet 5.5 and keep Opus 5.5 for the lead, as the costs page recommends. Name the model in the spawn prompt; it takes precedence over a subagent definition's
modeland overCLAUDE_CODE_SUBAGENT_MODEL. - Start with three teammates. The docs suggest 3 to 5 for most work and three even for 15 independent tasks, at five or six tasks per teammate.
- Keep spawn prompts short. Everything in them sits in the teammate's context from the first request.
- Shut teammates down as soon as their part is done, and press
xon a stuck one in the agent panel. - Give every reusable role a subagent definition with a
toolslist and amodel. A July report (issue #76970) describes a teammate whose definition had neither, which ran on Opus and spawned more agents. - Watch
/usageduring the first runs. The Claude Code cheat sheet lists the other commands that show where tokens go.
When agent teams are worth it
Use a team when the parts can run independently and the workers gain from talking to each other:
- Review with separate lenses, such as security, performance and tests, then a round where reviewers challenge each other's findings.
- Debugging with competing hypotheses. Anthropic's example spawns five teammates to disprove each other's theories, because one agent "tends to find one plausible explanation and stop looking".
- Research across several libraries or designs, one teammate per option.
- Cross-layer features where each teammate owns one layer's files and they agree on an interface as they go.
Skip the team when:
- The work is sequential, or each step needs the previous one's output.
- Several workers would edit the same files.
- Only the final result matters. Subagents return it for less.
- The job is the same change across hundreds of files. A dynamic workflow handles that with a script and warns you before the run gets large.
- You won't be watching. The docs warn that a team left unattended for long wastes effort, and the lead sometimes declares the work finished early.
A quick test: if three people could do the job without talking to each other, use subagents. If they'd need a shared channel, a team may earn its 2x to 7x.
What developers report
- On launch day, a Hacker News commenter answered a Pro user's question about limits by saying the feature does use up tokens very fast and suits companies paying by API more than individuals on a plan (Hacker News, 5 Feb 2026, link).
- "Token consumption scales with the product (teammates × notifications), not with actual work." (GitHub issue #47930 on lead idle-notification loops, opened 14 Apr 2026, link)
- "nested spawning burns 77% of 5h limit in <1 hour" (GitHub issue #76970, Max plan, Claude Code 2.1.207, 12 Jul 2026, link)
- "The cost is a permanently wedged session." (GitHub issue #89515 on idle teammates that were never evicted, 25 Aug 2026, closed as not planned, link)
- On the upside, a Hacker News commenter in October wrote that "agent teams and opus 5.5 is good enough for this by default", with no custom harness needed (Hacker News, 11 Oct 2026, link).
FAQ
How do you enable agent teams in Claude Code?
Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in the env block of settings.json or in your shell, then start an interactive session and ask Claude to create an agent team. Spawning teammates doesn't work with claude -p or the Agent SDK.
Are Claude Code agent teams free on Pro?
Anthropic lists no separate price for agent teams; the flag is a Claude Code setting. Every teammate's tokens come out of the same five-hour and weekly limits, so a team of four uses those limits several times faster than one session.
How many teammates can a Claude Code agent team have?
There is no hard limit. The docs recommend 3 to 5 teammates for most work, because token cost scales with each teammate and coordination overhead grows with team size.
Can each teammate use a different model?
Yes. Name the model per teammate in the spawn prompt, or use a subagent definition with a model field. Otherwise teammates run on the lead's model, and a teammate's model is fixed once it spawns.
Why does Claude spawn teammates instead of subagents?
With the flag on, any subagent that Claude gives a name launches as a teammate, and Claude names subagents on its own. Set the variable to 0 to get ordinary subagents back; the change applies to the next spawn without a restart.
Do agent teams work in VS Code?
The default in-process mode works in any terminal. Split-pane mode needs tmux or iTerm2 and isn't supported in VS Code's integrated terminal, Windows Terminal or Ghostty.
Sources
Anthropic, Claude Code docs:
- Orchestrate teams of Claude Code sessions (agent teams)
- Manage costs effectively
- Create custom subagents
- Run agents in parallel
- Orchestrate subagents at scale with dynamic workflows
- Tools reference: Task tool availability
- Hooks reference: TeammateIdle and TaskCompleted
- Model configuration
- Prompt caching
- Changelog
- npm registry: @anthropic-ai/claude-code dist-tags
Anthropic, other:
- Claude API pricing
- Claude plans and pricing
- Building a C compiler with a team of parallel Claudes (Nicholas Carlini, 5 Feb 2026)
GitHub, anthropics/claude-code:
- Issue #47930: lead loops on idle notifications
- Issue #76970: nested spawning and the 5-hour limit
- Issue #89515: idle teammates never evicted
Hacker News:
Checked on 10 November 2026.