Claude Code agent teams in 2026: the flag that quietly changes your subagents

Quick answer

Agent teams are Claude Code's experimental multi-session mode: one lead session spawns separate Claude Code instances that hold their own context windows, claim work off a shared task list, and message each other directly instead of reporting through the lead. As of August 2026 they are off by default and you turn them on with the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable set to 1.

The part worth knowing before you flip that switch has nothing to do with teams. Enabling agent teams also changes how ordinary delegation behaves: while the flag is on, a subagent that Claude names launches as a teammate, and teammates do not return their output the way subagents do. If you have a workflow that spawns a subagent and waits for its result, that workflow can stall. Anthropic's own documentation says so plainly, and it is the single thing I have not seen mentioned in any of the explainers currently ranking for this term.

On cost, the number circulating in Google's AI summary for this query is not the number in the docs. See the section below.

The flag is an environment variable, not a config key

This is the first place a reader gets sent off course. Google's AI Overview for claude code agent teams, checked August 27 2026, tells you to "turn on the experimental feature flag (claude_code_experimental_agent_teams) in your configuration settings."

That is lowercase, and it is described as a settings key. Neither is right. The agent teams documentation specifies an environment variable, uppercase, and when you put it in settings.json it goes inside an env block:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Write "claude_code_experimental_agent_teams": true at the top level of settings.json instead and nothing happens. No error, no warning, no team. You ask for teammates, Claude gives you subagents, and you spend twenty minutes wondering why the agent panel looks wrong. Setting it in your shell environment works equally well.

Worth noting for anyone turning it back off: the docs say Claude Code reapplies env values from a settings file to the running session when you save, and rereads the variable each time it spawns a subagent. So flipping it to 0 does not need a session restart.

The 7x number, and why nobody quotes it

Every secondary write-up on this topic asserts a token multiplier. Google's AI Overview says agent teams use "often 5x or more" tokens. At least one page on the first results page for this term argues the opposite direction, that teams come out several times cheaper per run. Neither cites a source.

Anthropic publishes a figure, and it is neither of those. From the cost management docs, read August 27 2026:

"Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode, because each teammate maintains its own context window and runs as a separate Claude instance."

Two things about that sentence matter more than the number.

First, it is conditional. The 7x is scoped to teammates running in plan mode. Every restatement I found drops the condition and quotes a bare multiplier, which is how a scoped figure turns into folklore.

Second, that sentence is not where you would look for it. The agent teams page links its token guidance to a #agent-team-token-costs anchor on the costs page, and that anchor section contains no multiplier at all. It gives you five sensible habits (run teammates on Sonnet, keep teams small, keep spawn prompts tight, shut teammates down when they finish, remember the feature is off by default) and no arithmetic. The 7x lives in a different section further down the same page, under general token reduction. Follow the doc's own link and you land on the half without the number.

I want to be straight about what this section is: I am quoting Anthropic's published figure, not a measurement of my own. That is the point. The reason to write this down is that three widely-read sources give three different multipliers pointing in two different directions, and only one of them is sourced at all.

The trap: turning teams on changes your subagents

Here is the mechanic I would want to know before enabling this on a machine that runs automation.

Claude launches a teammate when it calls the Agent tool with a name while agent teams are enabled. Claude also names ordinary subagents on its own, so it can message them later. Put those two together and you get the documented consequence: while agent teams are enabled, a named subagent launches as a teammate, so teams can form when you never asked for one.

That would be harmless if the two reported back the same way. They do not:

• A subagent completes and Claude receives its result.
• A teammate sends an idle notification when it stops, and that notification does not carry the teammate's output. A teammate shares results by messaging the lead or updating the shared task list.

So a flow built on "spawn a worker, wait for what it returns" quietly loses the return value. The docs put it in one line: an orchestration flow that waits on subagent results can stall.

The fix is the same variable, set to 0:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

One precedence detail that will cost somebody an afternoon: setting it to 0 in your user settings.json overrides a shell export, but project settings, local settings, a --settings payload, and managed settings all apply after user settings. Any of those setting it to 1 wins. If your organisation enables agent teams in managed settings, you cannot turn it off locally at all.

There is a related asymmetry that is genuinely useful: in non-interactive mode with the -p flag, including Agent SDK sessions, Claude does not spawn teammates, and a named subagent runs as an ordinary subagent even with the flag on. Interactive sessions get teams. Headless runs never do. If you script Claude Code in CI, the flag is inert there.

Two settings that are dead or moved

Both of these bite people following a tutorial written a few versions ago.

teammateDefaultModel was removed in v2.1.234, and Claude Code ignores a leftover value. It does not warn you. To control the teammate model now you either name it in the spawn prompt ("use Sonnet for each teammate") or set CLAUDE_CODE_SUBAGENT_MODEL.

The display mode default changed. It is "in-process" now, meaning everything runs inside your one terminal and you move between teammates with the arrow keys in the agent panel. Before v2.1.179 the default was "auto", which opens split panes when you are already inside tmux or in iTerm2 with the it2 CLI. So sessions that used to open panes stopped doing it after an upgrade, and it reads exactly like tmux broke. To get panes back:

{
  "teammateMode": "auto"
}

That goes in ~/.claude/settings.json. There is also a --teammate-mode flag for one session, which the docs note is experimental and does not appear in claude --help. Split panes need tmux or iTerm2, and are not supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.

The cache tax nobody mentions

This is the cost detail I would actually act on, and it is absent from every explainer I read.

An in-process teammate's requests fall outside the main conversation's cache TTL bucket. Its cache holds for five minutes by default, including on a Claude subscription, where the main conversation gets an hour. A teammate that pauses longer than five minutes reprocesses its context on the next turn.

You can buy the hour back by setting subagentPromptCacheTtl to 1h, with the tradeoff stated in the docs: the API bills one hour cache writes at a higher rate.

That is a much more useful mental model than a bare multiplier. The cost of a team is not a mystery number, it is one context window per teammate for as long as that teammate stays alive, plus a shorter cache window on each of them.

When I would reach for teams over subagents

I have written before about what I keep and delete in a subagents setup, and the honest answer is that agent teams do not replace that. The subagents docs and the teams docs describe genuinely different shapes, and the deciding question is not "how parallel is this" but "do the workers need to talk to each other."

Teams earn their overhead when the answer is yes. The documented strong cases are research and review, new modules where each teammate owns separate files, debugging competing hypotheses, and cross-layer changes. The debate case is the most interesting one, because the mechanism is the point: a single agent tends to find one plausible explanation and stop, and several investigators actively trying to disprove each other surface a root cause that survives challenge.

Subagents stay the right call for focused work where only the result matters, and the docs are explicit that for sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective. Two teammates editing one file leads to overwrites, so the work has to be splittable by file.

On team size, the docs give a number and it is smaller than you would guess: start with 3 to 5, and if you have 15 independent tasks, 3 teammates is a good starting point. Around 5 to 6 tasks per teammate. Three focused teammates often outperform five scattered ones.

Limitations to read before you turn it on

Agent teams are labelled experimental, and the limitations list is the most useful part of the page:

• No session resumption with in-process teammates. /resume and /rewind do not restore them, and the lead may then try to message teammates that no longer exist.
• Task status can lag. Teammates sometimes fail to mark tasks complete, which blocks anything depending on them.
• One team per session, no nested teams. Teammates cannot spawn teammates, and only the lead manages the team.
• The lead is fixed for the session's lifetime. You cannot promote a teammate.
• Permissions are set at spawn. Everyone starts with the lead's permission mode, and if the lead runs with --dangerously-skip-permissions, so does every teammate.

One security detail I was glad to see spelled out: when one agent messages another, Claude Code tells the recipient the message came from another Claude session rather than from you. A teammate cannot approve a permission prompt on your behalf, and a teammate denied an action cannot relay it to another teammate to get around the check.

Where the state actually lives

Useful for anyone debugging a stuck team. Teams are stored under a session derived name, session- followed by the first eight characters of the session ID:

~/.claude/teams/{team-name}/config.json
~/.claude/teams/{team-name}/inboxes/{agent-name}.json
~/.claude/tasks/{team-name}/

The mailbox is a JSON file per agent. The team config directory is removed when the session ends; the task list directory persists locally, is never uploaded, and is swept on the same cleanupPeriodDays schedule as your session transcripts. Do not hand edit the config: it holds runtime state like session IDs and pane IDs and is overwritten on the next state update.

One fixed bug worth knowing if you are on an older build: before v2.1.207, a single malformed mailbox entry caused a repeated error every second and blocked delivery for that mailbox until you deleted the file by hand. Current builds validate each entry, report the bad ones, remove them, and still deliver the valid messages.

What I took away

Agent teams are a real capability with a specific shape, and the shape is peer-to-peer coordination rather than parallelism for its own sake. Whether they pay for themselves depends on your workload, and I am not going to pretend a documentation read settles that.

What a documentation read does settle is that the two most visible answers to "what do agent teams cost" are both unsourced and point in opposite directions, that the published figure is 7x and carries a condition everyone drops, and that the flag has a side effect on ordinary delegation which is easily the most likely thing to surprise you. Turn it on deliberately, on a machine where nothing is waiting on a subagent's return value.

FAQ

How do I enable agent teams in Claude Code?
Set the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1, either in your shell or inside an env block in settings.json. It is an environment variable, not a top level settings key, and as of August 2026 the feature is disabled by default. Spawning teammates also requires an interactive session.

How much more do agent teams cost than a single session?
Anthropic's cost documentation, read August 27 2026, states approximately 7x more tokens than a standard session when teammates run in plan mode, because each teammate is a separate Claude instance with its own context window. Note the plan mode condition, which most restatements of this figure drop. Usage scales with the number of active teammates and how long each one runs.

What is the difference between agent teams and subagents?
Subagents run within a single session and return a result to the caller, and the main agent manages all the work. Teammates are fully independent sessions that message each other directly and coordinate through a shared task list. The practical difference is the return path: a subagent's output comes back to Claude, while a teammate only sends an idle notification that does not carry its output.

Do agent teams work in headless or CI runs?
No. In non-interactive mode with the -p flag, including Agent SDK sessions, Claude does not spawn teammates, and a subagent that Claude names runs as an ordinary subagent even with agent teams enabled.

Why did my terminal stop opening split panes for teammates?
The default display mode changed to "in-process"; before v2.1.179 it was "auto". Set teammateMode to "auto" in ~/.claude/settings.json to get split panes back when you are inside tmux or using iTerm2 with the it2 CLI installed.