Claude Code Agent Teams: What They Are and When to Use Them

Claude Code agent teams are an experimental feature that runs several Claude Code sessions as one team: a lead session assigns tasks and combines the results, while each teammate works in its own context window and messages the others directly (agent teams docs). The feature is off by default, so you turn it on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and then ask Claude for teammates in plain language. Every detail below was checked against the docs on October 3, 2026.

What is an agent team made of?

Four parts (architecture):

Each teammate loads CLAUDE.md, MCP servers and skills like a regular session, but not the lead's conversation history: it starts from the spawn prompt the lead writes (context and communication). So put the task details in that prompt (give teammates enough context).

How do you turn agent teams on?

Set the variable in your shell or in the env block of a settings file (enable agent teams):

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

Two side effects are easy to miss. Teammates spawn only in an interactive session, not with -p or in the Agent SDK. And while the variable is on, a subagent that Claude names launches as a teammate, so a team can form when you never asked for one (how Claude starts agent teams); setting it to 0 turns that off.

How do you start a team and steer it?

Describe the task and the teammates you want (start your first agent team). Name each teammate so you can refer to it later, and name the model too: the model your spawn prompt names is the first source Claude Code checks when it picks a teammate's model, unless CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 is set (specify teammates and models).

Spawn three teammates named ux, architect and skeptic to review this plan.
Use Sonnet for each. ux checks the user flow, architect checks the data
model, skeptic tries to disprove both. Report what you agree on.

Teammates appear in the agent panel below the prompt: arrow keys select one, Enter opens its transcript so you can message it, x stops it and Ctrl+T toggles the task list (talk to teammates directly). Subagents show in the same panel, so if Claude used them instead, ask again for an agent team explicitly. Split panes, which need tmux or iTerm2, are set with teammateMode in ~/.claude/settings.json or claude --teammate-mode auto (display mode).

How do teammates communicate?

Through messages and a shared task list (context and communication). A teammate messages another by name with the SendMessage tool, delivery is automatic, reaching everyone takes one message per recipient, and a finished teammate notifies the lead with its final answer. Tasks move through pending, in progress and completed, a task with unfinished dependencies cannot be claimed, and claiming uses file locking so two teammates cannot grab the same task (assign and claim tasks).

The catch is in the tools reference: from Claude Code v2.1.268, the Task tools behind that list are on by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6 and Haiku 4.5. An in-process teammate gets them only when the lead's session has them, and an agent without them coordinates through messages instead of the shared task list, unless you opt in, for example with CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude.

What can a teammate not approve for you?

Teammates start with the lead's permission mode, except dontAsk, and if the lead runs with --dangerously-skip-permissions, every teammate does too (permissions). Their permission prompts appear in the lead session, where you approve them. A message from another agent arrives marked as coming from another Claude session, not from you, so a teammate cannot approve a prompt or give consent on your behalf (messages between agents). One exception: a teammate's finished plan is approved by the lead's session without review, so a plan is not your checkpoint, though the edits that follow still prompt (plan approval). I approve every commit and every push on this blog, and agents never push on their own. Teammates load CLAUDE.md, so that rule would reach them, but a rule is not a check: start the lead with --dangerously-skip-permissions and every teammate skips permission prompts too, except explicit ask rules and the few actions no mode auto-approves (bypassPermissions).

What are the limits?

From the docs (limitations):

• /resume and /rewind do not restore in-process teammates.
• Task status can lag: a task nobody marked completed blocks the tasks that depend on it.
• Shutdown can be slow, because teammates finish their current request or tool call first.
• One team per session, no nested teams, and the lead is fixed.
• Split panes do not work in VS Code's integrated terminal, Windows Terminal or Ghostty.
• No worktree isolation, so give each teammate its own files (choose an approach).

Each teammate is a separate Claude instance, and the costs page puts teams at approximately 7x the tokens of a standard session when teammates run in plan mode (agent team costs). Teams cost more than subagents (compare with subagents), and the docs suggest 3 to 5 teammates for most work (team size).

When do subagents or a workflow fit better?

The docs frame the choice as who holds the plan (when to use a workflow):

Teams earn their cost when workers need to share findings and challenge each other: research and review, new modules owned by separate teammates, debugging with competing hypotheses, and changes that span frontend, backend and tests (when to use agent teams). For sequential tasks, same-file edits or work with many dependencies, the docs point to a single session or subagents. For a first team, they suggest work that needs no code written, such as reviewing a PR (start with research and review).

Does this blog's pipeline need a team?

Each article here goes through a multi-agent workflow: a writer and an independent fact-checker per article, editor passes, and an agent that renders every page in a real browser at desktop and phone width. One run on October 2, 2026 used 32 agents to write 13 manuals, tighten 5 drafts and render-check 20 pages (how that run is split). That is far past a handful of peers, and no agent in it needs to talk to another. The fact-checkers caught errors, such as a consent finding that held only because the check ran from Bulgaria, working independently of the writer. A team would let the writer message the checker and argue for its claims, which is exactly the channel a verifier should not have.

Where would a team earn its cost?

In the docs' debate example: teammates investigate different hypotheses and try to disprove each other's theories, to fight anchoring on the first plausible explanation (competing hypotheses). The consent finding had that shape, since the site's setup and the location of the check could each explain the same result. If I ran a team with the Task tools on, the first gate would be a TaskCompleted hook, which the docs suggest for lint checks: exit code 2 keeps the task from closing and feeds the errors back (TaskCompleted). Its input carries the task's title and description, not the changed files, so it would lint every changed MDX file with scripts/content_lint.py, as the Stop hook in the hooks manual does.

Where to start

Start with subagents, and move to a team only when the workers have something to say to each other. The writer and verifier pattern without a team is in Claude Code subagents: split the work, verify the result.