Claude Code Agent Teams: How to Enable Them, vs Subagents, and What They Cost (Tested on Windows)
Claude Code agent teams run several Claude sessions as a team: a lead plus named teammates that share a task list and message each other. How to turn them on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, how they differ from subagents, what a team cost next to subagents on the same task in my Windows test, and why teammates don't appear in claude -p.
Claude Code agent teams let one session, the lead, start several named teammates: each teammate is its own Claude Code session, and they share a task list and message each other. They're experimental and off by default. Turn them on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, start an interactive claude session, and ask for a team in plain words. In my Windows test a two-teammate team worked in the default in-process mode, cost about 1.7 times as much as two subagents (run in claude -p) on the same task, and never formed in claude -p itself.
| You want to | Do this |
|---|---|
| Turn agent teams on | CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your shell, or under "env" in settings.json |
| Start a team | In an interactive session: "Create an agent team with two teammates named …" |
| See and talk to teammates | Agent panel under the prompt: ↑/↓ to select, Enter to open, Esc to leave |
| Pick between teams and subagents | Workers need to talk to each other: team. Only the result matters: subagents |
| Run it on Windows | Default in-process mode works; split panes need tmux or iTerm2 |
| Teammates don't appear | Check you're not in claude -p, then ask explicitly for "an agent team" |
| Stop surprise teams | CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0 in settings.json |
Last reviewed 19 November 2026, against Anthropic's agent teams docs and the Claude Code changelog to 2.1.328. I ran the tests below on Claude Code 2.1.302 on Windows 11, in PowerShell inside VS Code's terminal, on a Max plan with Haiku 5.5, in a throwaway folder holding two two-line text files. Costs are Claude Code's own list-price estimates from one small run each, not a benchmark.
What are agent teams in Claude Code?
An agent team is a group of Claude Code sessions working together: a lead that you talk to, and teammates it starts and coordinates. From Anthropic's agent teams docs, what makes a team different from Claude simply delegating:
- Every teammate is a full session with its own context window, not a short-lived helper
- They share a task list, claim work from it and mark it done
- They message each other directly, not only through the lead
- You can talk to any teammate yourself, from the agent panel
Anthropic lists four places teams pay off: research and review, building separate modules in parallel, debugging with competing hypotheses, and changes that span frontend, backend and tests. For sequential work or several people editing the same file, the docs recommend a single session or subagents instead.
How do I enable agent teams in Claude Code?
Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, then use an interactive claude session. Either export it in your shell:
# PowerShell, this window only
$env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"
claude# macOS, Linux, WSL
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claudeOr turn it on for every session in your settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}Once CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set to 1, two things change. First, a team only forms in an interactive session: in claude -p and the Agent SDK, Claude uses ordinary subagents instead (tested below). Second, any subagent Claude gives a name now launches as a teammate, and Claude names subagents on its own, so teams can start when you didn't ask for one.
How do I start an agent team?
Describe the team in plain words: how many teammates, their names, and what each one does. Anthropic's docs say Claude Code doesn't ask you to confirm the launch, and in my session it didn't. This is the prompt I used, in a folder holding a.txt and b.txt:
Create an agent team with two teammates named reader-a and reader-b. reader-a reads a.txt
and reader-b reads b.txt. Each sends the first line of its file to the other teammate, then
reports both lines to you. Then shut the team down.Claude Code printed 2 background agents launched (↓ to manage) with @reader-a and @reader-b under it, and the agent panel below the prompt listed main, reader-a teammate: read a.txt and reader-b teammate: read b.txt. Messages between them showed as Message from @reader-a (ctrl+o to expand), and each teammate reported back with a Teammate @reader-a finished row.
Both teammates read their file, sent the first line to the other, and the lead reported alpha: the first file and beta: the second file, which is right. Two things went less smoothly, and both are worth knowing:
- The lead gave the teammates a
/tmppath. On Windows the files only resolved through the real Windows path of the folder, which both teammates noticed and worked around. If you name files for a team on Windows, use paths relative to the project. - Shutdown never confirmed. The lead sent shutdown requests and reported: "The shutdown requests are still unconfirmed. Both teammates have gone idle, but I haven't received a shutdown response from either." Anthropic lists slow shutdown as a known limitation, and later versions fixed several shutdown bugs (version table), so update before relying on it.
From the agent panel: ↑ and ↓ select a teammate, Enter opens its transcript so you can message it directly, and Esc clears the selection or interrupts the teammate you're viewing. Ctrl+T toggles the task list.
Agent teams vs subagents: what's the difference?
In Claude Code, subagents work for the main agent and report one result back; teammates are full sessions that coordinate with each other.
| Subagents | Agent teams | |
|---|---|---|
| What each worker is | A helper with its own context, returning a result to its caller | A full Claude Code session with its own context |
| Talking to each other | Only named subagents, and mainly through the main agent | Teammates message each other directly |
| Coordination | The main agent manages everything | A shared task list plus messages |
Works in claude -p | Yes | No |
| Token cost | Lower | Higher: each teammate is a separate instance |
| Best for | Focused tasks where only the result matters | Work where the workers must share findings or challenge each other |
This comparison follows Anthropic's subagents vs agent teams table in the Claude Code docs. If two jobs don't need to talk, subagents are the cheaper and simpler choice, and they also work in scripts and CI.
How much do Claude Code agent teams cost?
More than subagents, and the gap grows with every teammate, because each teammate has its own context window. In one run on Claude Code 2.1.302 with Haiku 5.5 (19 November 2026), a two-teammate team cost $0.048 against $0.028 for two subagents. I ran the same task both ways with Haiku 5.5 and read the cost Claude Code reports at list price:
| Same task: read two files, exchange first lines | Two subagents (claude -p) | Two-teammate agent team (interactive) |
|---|---|---|
| Cost at list price | $0.028 | $0.048 |
| Cached input read | about 304K tokens | about 1.3M tokens |
| Cache written | about 148K tokens | about 198K tokens |
That's about 1.7 times the cost and over four times the cached input for a task with almost no real work in it, most likely because each teammate is a full session that loads its own copy of Claude Code's tools and instructions. The two runs aren't a clean comparison: the subagents ran in claude -p because teams can't, and an interactive session loads more on its own. Read the ratio as a rough size, not a measurement. On a Claude subscription this is usage against your limits rather than a bill: my 5-hour bar read 6% before and after, so a tiny Haiku team barely registers. A team of Opus teammates on a real codebase is a different matter, and it's one way people end up at a 429 throttle: in the GitHub thread behind my Claude Code error 429 post, two Max subscribers say it starts when they run a team of subagents.
Two settings matter for cost. Per the token usage section of Anthropic's docs, an in-process teammate's prompt cache lasts five minutes by default even on a subscription, so set subagentPromptCacheTtl to 1h if teammates sit idle between steps. And give teammates a cheaper model in your prompt (for example "use Sonnet for the teammates") when the work allows. For where the rest of the tokens go, see why Claude Code uses so many tokens.
Do Claude Code agent teams work on Windows?
Yes. Claude Code agent teams work on Windows in the default in-process mode; I tested it on Claude Code 2.1.302 in PowerShell on Windows 11. Teammates run inside your main terminal and appear in the agent panel, so any terminal works, including PowerShell and VS Code's terminal on Windows.
The other display mode, split panes, gives every teammate its own pane and needs tmux or iTerm2. Neither exists in plain PowerShell or cmd, so on Windows you stay in in-process mode unless you run Claude Code somewhere tmux works, such as WSL; I haven't tested split panes there. The teammateMode setting chooses the mode: "in-process", "tmux", "iterm2" or "auto", where auto uses split panes only when Claude Code is already running inside tmux or iTerm2.
Why does Claude use subagents instead of an agent team?
Either the session can't run a team, or Claude decided the task didn't need one. I hit the first case on purpose: with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 set, I asked claude -p for "an agent team with two teammates". The job finished, but Claude answered that agent teams weren't available in that session and used two subagents instead, exactly as Anthropic's docs say happens in non-interactive mode.
In an interactive session, if Claude still uses subagents, ask again and say "create an agent team" with the teammates named. The agent panel shows subagents and teammates in the same place, so look for the teammate: label on each row to be sure a team formed.
Why aren't my Claude Code agent teammates working?
| Symptom | Cause and fix |
|---|---|
| Teammates never appear | You're in claude -p, the variable isn't set in that shell, or the task looked too small; set it, use an interactive session, and ask explicitly |
| A teammate row disappeared | It's hidden, not stopped: idle rows hide 30 seconds after the whole panel goes idle. Message the teammate by name to bring it back |
| Teams start when you didn't ask | A named subagent becomes a teammate while teams are on. Set the variable to 0 in settings.json; it's reread for every new subagent |
| Endless permission prompts | Teammates' prompts all land in the lead. Pre-approve common commands in your permission settings before starting the team |
| Teammates edit as freely as the lead | They start in the lead's permission mode, including auto and bypass; my session started in auto mode. See Claude Code auto mode |
| A teammate stops early, or the lead declares victory too soon | Open the teammate, give it more instructions, or tell the lead to keep going |
| Shutdown never confirms | A known limitation; teammates finish their current step first. Update Claude Code, since 2.1.304 and 2.1.317 fixed shutdown bugs |
After /resume, the lead messages teammates that are gone | In-process teammates aren't restored. Ask the lead to start new ones |
Several in-process teammates fail with Lock file is already being held | Update: 2.1.328 made this far less frequent |
What are the limits of agent teams?
Claude Code agent teams have these documented limitations in Anthropic's docs (checked 19 November 2026): one team per session, no nested teams (teammates can't start their own), the lead is fixed for the session, no per-teammate permission mode at spawn, no session resumption for in-process teammates, task status that can lag, and slow shutdown. In-process teammates also can't start background subagents. Teams don't put teammates in separate git worktrees, so split the work so no two teammates edit the same file.
Anthropic suggests three to five teammates for most work, with tasks sized so each teammate has a clear, self-contained piece. If you want a guard that refuses risky tool calls whichever teammate makes them, a Claude Code mod can do that from inside Claude Code.
Which Claude Code versions changed agent teams?
| Version | Change |
|---|---|
| 2.1.328 | Starting several in-process teammates at once: far fewer fail with Lock file is already being held |
| 2.1.327 | In-process teammates on a different model from the lead now compact at their own context limit, on their own model |
| 2.1.326 | Code Mode can be turned on while agent teams are enabled |
| 2.1.325 | An unknown teammateMode value is now reported instead of silently ignored; tmux and iTerm2 teammates start in the session's folder |
| 2.1.323 | Split-pane teammates check that requests come from their lead |
| 2.1.317 | Fixed tmux and iTerm2 teammates starting in auto mode when the lead was in manual mode; fixed a re-created teammate being removed by an earlier shutdown approval |
| 2.1.311 | Fixed an empty task list after --resume, --continue or /resume |
| 2.1.309 | Split-pane teammates inherit the lead's --disallowedTools and --tools rules |
| 2.1.304 | Approving a shutdown request from the main session no longer exits the whole CLI |
| 2.1.295 | Fixed in-process teammates failing their first SendMessage until they loaded the tool |
From the changelog. I tested on 2.1.302, before the 2.1.304 and 2.1.317 shutdown fixes, which may explain the shutdown that never confirmed.
Key takeaways
- Claude Code agent teams are a lead plus named teammates, each a full session, sharing a task list and messaging each other. They're experimental and off by default.
- Enable them with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and an interactive session; in claude -p Claude uses subagents instead, which I confirmed.
- Use subagents when only the result matters; use a team when workers need to share findings or challenge each other.
- In my Windows test a two-teammate team cost $0.048 against $0.028 for two subagents on the same task, with about 4x the cached input.
- In-process mode works on Windows; split panes need tmux or iTerm2. Use project-relative paths: my lead handed teammates a /tmp path.
- While teams are on, any named subagent becomes a teammate. Set the variable to 0 in settings.json to stop surprise teams.
FAQ
Frequently asked questions
What are agent teams in Claude Code?
Agent teams are an experimental Claude Code feature where one session, the lead, starts several named teammates. Each teammate is its own Claude Code session with its own context window; they share a task list and can message each other directly, while the lead assigns work and collects the results. They are off by default.
How do I enable agent teams in Claude Code?
Set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, either in your shell or under "env" in settings.json, then start an interactive claude session and ask for a team in plain words, for example 'Create an agent team with two teammates named reader-a and reader-b'. Anthropic's docs say teams don't form in claude -p or Agent SDK sessions, and my claude -p test used subagents instead.
What is the difference between agent teams and subagents?
Subagents are workers the main agent starts; each does its task and returns one result to the main agent rather than to each other. Agent teammates are full Claude Code sessions that share a task list and message each other, coordinated by a lead. Teams suit work where the workers need to compare notes; subagents are cheaper for focused tasks where only the result matters.
Do Claude Code agent teams cost more?
Yes. Each teammate is a separate Claude instance with its own context, so usage grows with the number of teammates. In my test on Claude Code 2.1.302 with Haiku 5.5, the same two-file task cost $0.028 at list price with two subagents and $0.048 with a two-teammate agent team, with about four times the cached input. On a Claude plan that is usage against your limits, not a bill.
Do Claude Code agent teams work on Windows?
Yes, in the default in-process mode: teammates appear in the agent panel under the prompt, and you switch between them with the arrow keys. I ran a two-teammate team in PowerShell in VS Code's terminal on Windows 11. Split-pane mode needs tmux or iTerm2, so it isn't available from plain PowerShell or cmd.
Why does Claude use subagents instead of creating an agent team?
Either the session can't run teams or Claude chose not to. Teams only form in interactive sessions with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1; in claude -p, Anthropic's docs say Claude uses subagents instead, which my test confirmed. In an interactive session, ask again and explicitly say 'create an agent team' and name the teammates.
Why do agent teams start when I didn't ask for one?
While agent teams are enabled, any subagent Claude gives a name launches as a teammate, and Claude names subagents on its own so it can message them later. To get ordinary subagents back, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 0 in settings.json; Claude Code rereads it each time it spawns a subagent.
How many teammates should an agent team have?
Anthropic's docs suggest starting with three to five teammates for most work. There is no hard limit, but token use grows with every teammate and coordination gets harder, and the docs note that three focused teammates often outperform five scattered ones.
Related
References
- Orchestrate teams of Claude Code sessions (Claude Code docs)code.claude.com · accessed 2026-11-19
- Run agents in parallel: subagents, agent view, agent teams, dynamic workflows (Claude Code docs)code.claude.com · accessed 2026-11-19
- Subagents (Claude Code docs)code.claude.com · accessed 2026-11-19
- Agent team token costs (Claude Code docs)code.claude.com · accessed 2026-11-19
- Claude Code changelog: agent team and teammate fixes, 2.1.260 to 2.1.328github.com · accessed 2026-11-19
Last reviewed November 19, 2026
Tahir Nazir
Senior AI Engineer & Full-Stack Lead
5+ years shipping AI-powered products — RAG pipelines, agentic workflows, and MCP tooling. Top Rated on Upwork with a 100% job success score.
More about Tahir →Related articles
Claude Code Error 429: 'Server Is Temporarily Limiting Requests' and 'Request Rejected (429)' Explained
Claude Code shows a 429 in two different ways. 'API Error: Server is temporarily limiting requests (not your usage limit)' is a short server-side throttle on a claude.ai subscription; 'API Error: Request rejected (429)' is the rate limit of your API key, Bedrock or Vertex project. Which one you have, why it is not your usage limit, what Claude Code already retried, and how to fix each.TroubleshootingAI Engineering17 min readClaude Code Tokens: How Many It Uses, How to See Them, and How to Cut Them
A two-token prompt made Claude Code process about 38,000 tokens before it answered, and 54,000 with my plugins and MCP servers loaded. Where Claude Code's tokens go, how to see them with /usage, /context and the status line, what it costs, why usage climbs while you're idle, and the changes that actually cut it.TroubleshootingAI Engineering19 min readClaude Code Auto Mode Is Now the Default: Turn It Off, or Keep It
Claude Code now starts in auto mode: 'Auto mode is now Claude Code's default permission mode.' What auto mode does, how to turn it off with permissions.defaultMode or Shift+Tab, how it compares with accept edits, plan and bypass permissions, and what each 'auto mode unavailable' message means.How-toAI Engineering23 min read
Follow along
New posts land here first. Follow along by RSS, or get in touch if you are building something similar.