Claude Code Agent Teams vs Subagents: When Multi-Agent Mode Is Worth the Tokens

If you already run Claude Code subagents every day, you probably don't need Agent Teams. Subagents should stay your default. Turn on a team for three job shapes: a parallel review where each reviewer gets one lens, a bug hunt with competing theories, and a feature that cuts across layers where every teammate owns its own files. Outside those, you're paying for coordination you don't use, and the bill is real: Anthropic's cost guide puts agent teams at roughly 7x the tokens of a standard session when teammates run in plan mode.

Anthropic shipped Agent Teams alongside Opus 4.6 on February 5, 2026, as a research preview (TechCrunch). Almost nine months later it is still off by default and still labeled experimental in the Claude Code docs, gated behind a single environment variable. The docs page has grown anyway, and now covers split panes, quality-gate hooks, reusable roles, and a model-selection order.

Everything below was checked against the live Claude Code docs on October 29, 2026. The feature moves fast, so where a behavior depends on a version, we say which.

Subagents report up, teammates talk sideways

The cleanest way to hold the difference: a subagent is a worker you send off and wait for. A teammate is a separate Claude Code session that sits on a shared board with its peers. Anthropic's own comparison says subagents "report results back to the main agent," while teammates "share a task list, claim work, and communicate directly with each other."

	Subagents	Agent teams	Source
Context	Own window; result returns to the caller	Own window; a full separate session	Agent teams docs
Who coordinates	The main agent manages all work	Teammates self-coordinate through messages and a shared task list	Agent teams docs
Nesting	Up to three layers below the main conversation by default	None: teammates can't spawn teammates	Subagents docs, limitations
Running at once	Spawning fails at 20 concurrent subagents by default	No hard cap; docs suggest starting with 3 to 5	Subagents docs, team size
Token cost	Lower; results summarized back	Roughly 7x a standard session with teammates in plan mode	Agent teams docs, cost guide
Works headless (-p, Agent SDK)	Yes	No, named subagents run as ordinary subagents there	Enable agent teams

Subagents are more team-like than their reputation. By default they spawn their own subagents up to three layers deep, the agent teams page notes that subagents Claude named when it spawned them "can also message each other," and you can open a running subagent's transcript and send it follow-ups. Our subagents and hooks guide covers the basics of that primitive; the limits above are the current numbers.

So what does a team give you that named, nested subagents don't? Workers that pull their own next job from a shared task list, with dependencies and claiming, instead of waiting for the main agent to hand it out. And workers that are full Claude Code sessions: you can put one in plan mode, give it its own terminal pane, and hold it with a TeammateIdle hook until its output checks out.

Turning it on, and the side effect the docs flag

One variable, set in your shell or in settings.json. Per the docs:

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

With teams enabled, any subagent that Claude names launches as a teammate instead. Claude names subagents on its own so it can message them later, which means a team can form during ordinary delegation you never framed as team work, and Claude Code doesn't ask you to confirm the launch. You flip the flag to try one experiment, forget about it, and a week later a routine "go check the tests" spins up a full session with its own context window.

To undo it, set the variable to 0 and save. Claude Code reapplies settings-file env values to the running session and rereads the variable each time it spawns a subagent, so you don't need a restart. One wrinkle: a 0 in your user settings.json overrides a shell export, but project, local, and managed settings all apply after your user file, so a 1 in any of them still wins.

Teammates also need an interactive session. In -p mode and in the Agent SDK, Claude doesn't spawn them at all.

Your first team, with a prompt that holds up

You describe the team in plain language and the lead does the rest. What separates a good spawn prompt from a vague one is names, a model, and file ownership. Teammates don't inherit the lead's conversation history (context docs), so anything they need goes in the prompt:

Create an agent team for the billing-export feature. Spawn three teammates
and call them api, ui, and tests. Use Sonnet for each.
- api owns src/server/export/ only
- ui owns src/web/export/ only
- tests owns tests/export/ only
Create tasks with dependencies so tests waits on api. Wait for your
teammates to finish before you write anything yourself.

Naming them pays off later, because you can say "ask tests to rerun the suite" and the lead knows who you mean. The last line is there because the docs call out a lead that starts implementing tasks itself instead of waiting.

In the default in-process mode the teammates show up in an agent panel under your prompt. Arrow keys select one, Enter opens its transcript so you can type to it directly, x stops it, and Ctrl+T toggles the task list (controls). Don't panic when rows vanish: once every agent is idle, idle rows hide after 30 seconds and come back on the teammate's next turn, per the docs, while the teammate keeps running.

Check that you actually got a team, too. Subagents appear in the same panel, so the panel alone doesn't prove one formed. If Claude delegated to subagents, ask again and say "agent team" explicitly.

Three jobs where the extra tokens pay for themselves

Parallel code review. One reviewer drifts toward one class of issue at a time. Split the lenses and they don't overlap. Anthropic's example gives one teammate security, one performance, one test coverage, all on the same PR, and the lead synthesizes. Read-only work like this is also where the docs tell newcomers to start, since nobody can overwrite anybody.

Debugging with competing hypotheses. This is the use case we'd turn teams on for first. A single agent finds one plausible cause and stops looking. The docs' example prompt spawns five teammates and tells them to try to disprove each other "like a scientific debate." The mechanism is anchoring: sequential investigation leans toward whatever theory got explored first, and a debate breaks that. You can approximate it with named subagents, but each one is built to hand a result back to the caller, so the arguing tends to get routed through the main agent instead of happening between investigators.

Cross-layer feature work. Frontend, backend, tests, each owned by a different teammate, with the task list holding the dependency order. It works only if you partition files. The docs are blunt about it: "Two teammates editing the same file leads to overwrites" (best practices).

What these three share is that teammates can run for a while without waiting on each other. Hand a team a sequential chain and you're paying several context windows to do one thing slowly.

The control-plane shape, now in your terminal

A task board, named roles, agents messaging each other, a gate before work counts as done: Pondero's own scout, writer, and reviewer roles used to get that shape from Paperclip AI, a separate agent control plane. Agent Teams puts the same shape inside the CLI, on your machine, with no extra service.

Three design choices hold up. Task claiming uses file locking, so two teammates can't grab the same task, which is the first race condition we'd expect a homegrown task board to hit. Each agent's mailbox is a JSON file under ~/.claude/teams/{team-name}/inboxes/, delivery is automatic, and a teammate that finishes notifies the lead with its final answer, so nobody polls (architecture). And a message from another agent is marked as coming from another Claude session: it can't approve a permission prompt on your behalf, and a denied teammate can't launder the request through a peer.

The rough edges are listed plainly in the limitations, and three of them shape how you'd use it:

• /resume and /rewind don't restore in-process teammates. After a resume, the lead may message teammates that no longer exist; tell it to spawn fresh ones.
• Task status can lag. Teammates sometimes fail to mark a task complete, which blocks everything that depends on it.
• One team per session, no nested teams, and the lead is fixed for the session's lifetime. You can't hand leadership to a teammate or share a team across sessions.

Task lag is the one you'll hit. It's also the one a hook can catch.

Four settings to know before your first team

Reuse a subagent definition as a teammate role

Any subagent in your project, user, managed, or plugin scope can become a teammate. Ask for it by type: "Spawn a teammate using the security-reviewer agent type to audit the auth module." Claude Code then applies the definition's tools and model in both display modes (docs). Two exceptions matter: the definition's skills field is never applied to a teammate, and mcpServers applies only to split-pane teammates. Define a role once in .claude/agents/ and you get it as a delegated subagent and a teammate.

Know which model each teammate gets

Claude Code picks a teammate's model from the first of these that applies, per the model order:

1. The model your spawn prompt names for that teammate.
2. The subagent definition's model field, if the teammate came from one (inherit means the lead's model).
3. CLAUDE_CODE_SUBAGENT_MODEL, when it's set to anything other than inherit.
4. The lead's current model.

That order needs Claude Code v2.1.257 or later; before v2.1.251 the environment variable came first (same section). If you want one model forced onto every teammate, set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 and the first two sources drop out. The cost guide recommends Sonnet for teammates, and with a roughly 7x multiplier in play (cost guide), naming the model in your spawn prompt is the cheapest habit you can build.

Split panes, if your terminal supports them

The default teammateMode is "in-process". Set it to "auto" in ~/.claude/settings.json and Claude Code uses split panes when you're already inside tmux or running iTerm2 with the it2 CLI, falling back to in-process otherwise (display modes). For one session there's also a flag, which the docs note is experimental and missing from the CLI's help output:

claude --teammate-mode auto

Split panes don't work in VS Code's integrated terminal, Windows Terminal, or Ghostty, per the limitations list. If that's where you live, stay in-process.

Gate the work with the three team hooks

Three hook events in the hooks reference do the quality control for a team: TeammateIdle fires when a teammate is about to go idle, TaskCreated when a task is being created, and TaskCompleted when one is being marked complete. On all three, a command hook that exits with code 2 blocks the action and feeds your stderr message back to the model. None of them take matchers; they fire every time.

TaskCompleted is the one we'd wire up first, because it turns "the teammate says it's done" into "the tests say it's done." In your project's .claude/settings.json:

{
  "hooks": {
    "TaskCompleted": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/require-tests.sh"
          }
        ]
      }
    ]
  }
}

And the script, adapted from the hooks reference example (make it executable with chmod +x):

#!/bin/bash
# .claude/hooks/require-tests.sh
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')
if ! npm test 2>&1; then
  echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
  exit 2
fi
exit 0

The hook input carries task_id, task_subject, and, when present, teammate_name, so you can scope stricter checks to one role. TaskCompleted also fires when a teammate ends its turn with tasks still in progress, which is exactly the moment the status-lag limitation would otherwise slip past you.

When a team is the wrong tool

Anthropic says it directly: for "sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective" (when to use). The same page's token usage section adds routine tasks, where "a single session is more cost-effective." Renaming a function across a repo, writing a migration, bumping dependencies: one session does these fine, and a team just multiplies the context.

There are two lighter options between "one session" and "a team." If you're already running several sessions yourself, say in separate git worktrees, cross-session messaging lets Claude pass a finding from one to another with nothing to enable, on v2.1.224 or later for macOS and Linux. Claude can even ask another local session to notify it when that session goes idle. And for verbose side work you only need a summary of, a plain subagent is still the right call.

Our pick: turn it on for review and debugging, keep subagents as the default

• Solo developer doing day-to-day feature work: leave Agent Teams off. Subagents, which nest and can message each other by name, cover delegation without the token multiplier or the surprise-teammate side effect.
• Lead or reviewer stuck on a bug with no obvious cause, or a PR that needs several lenses: enable it for that session, spawn the 3 to 5 named teammates the docs suggest on Sonnet, and set the flag back to 0 when you're done. Competing-hypothesis debugging is the job where a team does clearly better than subagents.
• Team building a feature across frontend, backend, and tests: worth it if you can assign each teammate its own directories and you wire up a TaskCompleted hook before you start. Skip the hook and the status-lag limitation can stall your dependent tasks.
• CI and headless pipelines: not an option. Teams don't spawn under -p or the Agent SDK, so build those on subagents.

If you're still deciding which coding agent to standardize on in the first place, start with our Claude Code vs Cursor comparison before you spend tokens on multi-agent setups.