Agent teams

An agent team is a group of Claude Code sessions with one in charge. The lead is your main session: it splits the work, spawns teammates, hands out tasks and pulls the results together. Each teammate has its own context window and can message the others directly, and you can talk to any of them without going through the lead.

Warning: Agent teams are experimental and disabled by default. Until you set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, no team is created, no team folders are written and Claude never proposes teammates. Expect rough edges around resuming, task tracking and shutdown (see Limitations).

Before reaching for a team, check whether something lighter will do. Subagents cover most delegation inside one session, and cross-session messaging lets sessions you started yourself share findings.

When a team earns its keep

Teams shine when several workers can explore in parallel and benefit from arguing with each other:

• Research and review, where different teammates examine different angles and challenge each other's conclusions.
• New features or modules that split cleanly, with each teammate owning one part.
• Debugging with rival theories, where each teammate tries to prove its hypothesis and disprove the others.
• Cross-layer changes where frontend, backend and tests each have an owner.

They cost noticeably more tokens than a single session and add coordination overhead. For sequential work, edits to the same file, or tightly interdependent tasks, stay with one session or a few subagents.

Teams versus subagents

Turning teams on

Set the variable in your shell or in settings:

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

Be aware this changes ordinary delegation too. Claude sometimes names subagents on its own so it can message them later, and with teams enabled any named subagent launches as a teammate. Teams can therefore appear when you never asked for one. See Claude spawns teammates instead of subagents if that bothers you.

Teams need an interactive session. In headless mode with -p, and in Agent SDK sessions, Claude does not spawn teammates and named subagents stay ordinary subagents.

Your first team

Describe the job and the roles in plain English. Independent roles work best for a first try:

We need to decide how to add offline support to the field-inspection app.
Spawn three teammates: one to research sync strategies for IndexedDB, one
to audit which API calls the app makes today, and one to argue for keeping
it online-only. Have them compare notes and give me a recommendation.

In a session that has the Task tools, Claude fills a shared task list, spawns the teammates, lets them work and then summarises.

Claude sometimes uses subagents instead. Both appear in the same panel, so the panel alone does not prove a team formed. If you wanted a team, ask again and say "agent team" explicitly.

The agent panel under the lead's prompt lists teammates:

• ↑ and ↓ select a teammate.
• Enter opens its transcript so you can message it.
• Esc clears the selection; while viewing a teammate, it interrupts that teammate's turn.

Idle teammates stay visible while anyone else is working. Once everyone is idle, their rows hide after 30 seconds but the teammates keep running and can still be messaged. With more than three idle at once, the extras collapse into a single row such as 2 idle agents; Enter expands it.

Steering the team

Mostly you just talk to the lead in plain language. A few controls are worth knowing.

Display modes

• In-process (default): every teammate runs inside your terminal and you switch between them in the panel. Works anywhere.
• Split panes: each teammate gets its own pane, so you can watch them all. Needs tmux or iTerm2.

The teammateMode setting in ~/.claude/settings.json picks the mode:

{
  "teammateMode": "auto"
}

For one session, use the (hidden, experimental) flag claude --teammate-mode auto.

To set up split panes, install tmux through your package manager, or install the it2 CLI and enable iTerm2 → Settings → General → Magic → Enable Python API. tmux behaves best on macOS, and tmux -CC inside iTerm2 is a good way in. Split panes are not supported in VS Code's integrated terminal, Windows Terminal or Ghostty.

Team size and models

Let Claude decide, or be specific:

Spawn 3 teammates on Haiku to update the copy in each of the three locale files.

A teammate's model comes from the first of these that applies:

1. A model named for it in your spawn prompt
2. The model of the subagent definition it was spawned from (inherit means the lead's model)
3. CLAUDE_CODE_SUBAGENT_MODEL, unless set to inherit
4. The lead's current model

A mod's agent.spawn hook can replace step 1. With CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (v2.1.257+), steps 1 and 2 are skipped. The old teammateDefaultModel setting was removed in v2.1.234 and is ignored. Choices are checked against your organisation's availableModels allowlist, falling back to a permitted version of the family or to the lead's model. Teammates inherit the lead's effort level.

Plan first, then build

For risky changes, put the lead into plan mode before asking for the teammate. A teammate spawned while the lead is in plan mode works read-only until its plan is ready, then sends an approval request. The lead's session approves it automatically, without a separate prompt to you, and the teammate starts implementing. Its edits and commands still go through the normal permission prompts.

Talking to teammates directly

Every teammate is a full session. In in-process mode, select it, press Enter and type. x stops the selected teammate and Ctrl+T toggles the task list. In split-pane mode, click into its pane.

While viewing an in-process teammate, text and skills go to the teammate but built-in commands go to the lead. /compact, /clear and /rewind ask for confirmation because they would affect the lead, and /model and /fast refuse to run since a teammate's model and fast mode are fixed at spawn.

The task list

The lead creates tasks; teammates work through them. Tasks are pending, in progress or completed, and can depend on other tasks: a blocked task cannot be claimed until its dependencies finish, and completing one unblocks its dependents automatically. You can tell the lead who should take what, or let teammates self-claim the next unblocked task. Claiming uses file locks so two teammates cannot grab the same item. Agents without the Task tools coordinate through messages instead.

Shutting down

Ask by name: Tell the sync-researcher teammate to wrap up and shut down. The lead sends a shutdown request; the teammate either exits cleanly or declines with a reason. Team folders are cleaned up when the session ends.

Quality gates with hooks

Three hook events are built for teams. Exit code 2 from any of them blocks the action and sends your message back:

I use TaskCompleted to run the relevant test file and refuse completion if it fails.

How it works underneath

How a team starts

A teammate is launched whenever Claude calls the Agent tool with a name while teams are enabled, unless the call is a fork or passes isolation itself. There is no confirmation prompt.

Parts of a team

Each agent's mailbox is ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. Malformed entries are reported and removed while valid messages still deliver. A message counts as sent only once the write succeeds; a full disk or read-only folder gives the sender an error.

The team name is session- plus the first eight characters of the session ID. The team config lives at ~/.claude/teams/{team-name}/config.json and is removed when the session ends. The task list lives at ~/.claude/tasks/{team-name}/, stays on your machine, survives for resumed sessions and is cleaned up under cleanupPeriodDays.

The config holds runtime state (session IDs, tmux pane IDs) and a members array with each member's name, agent ID and agent type (team-lead for the lead). Teammates can read it to find each other. Do not edit or pre-write it; it gets overwritten. A project file like .claude/teams/teams.json means nothing to Claude Code.

Reusing subagent definitions as teammates

Define a role once as a subagent (project, user, managed or plugin scope) and spawn teammates from it:

Spawn a teammate using the accessibility-auditor agent type to check the checkout flow.

What carries over depends on the display mode:

If Claude messages an in-process teammate that has stopped, Claude Code revives it in the same session with its saved conversation. A definition from a project's .claude/agents/ is re-applied only if you trusted that exact folder.

Permissions

Teammates start in the lead's permission mode, except dontAsk, which they do not inherit. If the lead runs with --dangerously-skip-permissions, so do they. You can change a teammate's mode after spawning but not set it per teammate at spawn. Teammate permission prompts appear in the lead's session for you to answer; plan approval is the one thing the lead grants automatically.

Messages between agents are labelled as coming from another Claude session. A teammate cannot approve a prompt for you, and one that was refused something cannot ask another to do it instead. In auto mode, the classifier treats relayed approvals as untrusted and reviews every message (including shutdown requests and plan approvals) before delivery.

Context

Each teammate loads the same project context as a fresh session (CLAUDE.md, MCP servers and skills) plus the lead's spawn prompt. It does not get the lead's conversation. --setting-sources on the lead limits teammates to the same sources.

Information flows through automatic message delivery (no polling), idle notifications that include each teammate's final answer (or error), the shared task list, and direct messages by name. There is no broadcast, so reaching everyone means one message each. Tell the lead what to call each teammate if you want predictable names.

Tokens

Cost scales with the number of active teammates. An in-process teammate's prompt cache lasts five minutes by default; set subagentPromptCacheTtl to 1h to keep it longer, at a higher write price. See Costs and Prompt caching.

Two prompts I reuse

A three-lens PR review:

Create an agent team to review PR #87. One teammate looks only at security,
one at query performance, one at whether the tests actually cover the new
branches. Each reports findings with file and line, then you merge them into
one review ordered by severity.

Competing hypotheses for a nasty bug:

Uploads over 50MB silently fail in production but not locally. Spawn four
teammates, each owning one theory (proxy limits, multipart parsing, S3
presign expiry, client timeout). They should actively try to disprove each
other's theories. Write whichever explanation survives to docs/incidents/upload.md.

The adversarial framing matters. One investigator tends to anchor on the first plausible cause; several trying to knock each other down are far more likely to land on the real one.

Habits that help

• Front-load context. Teammates do not see your chat, so put file paths, constraints and the "why" in the spawn prompt.
• Start with three to five teammates. Costs grow linearly and coordination grows faster. Three focused teammates usually beat five vague ones.
• Aim for five or six tasks per teammate, each producing something concrete such as a function, a test file or a written review.
• Tell the lead to wait if it starts doing the work itself: "Let your teammates finish before you continue."
• Begin with read-only work like reviews and research before trying parallel implementation.
• Give each teammate its own files. Two teammates editing one file will overwrite each other.
• Check in regularly. A team left alone too long wastes effort.

Troubleshooting

No teammates appear

• In in-process mode, look in the panel under the prompt and use the arrow keys.
• A row that vanished while idle is hidden, not gone; message the teammate by name to bring it back.
• The task may not have seemed big enough. Ask for a team explicitly.
• For split panes, check which tmux, or that it2 is installed and iTerm2's Python API is on.

Claude spawns teammates instead of subagents

Turn teams off with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS set to 0 in your settings env. Settings-file changes apply to the running session on save. Project, local, --settings and managed values that set it to 1 still win over user settings. Named subagents remain addressable through SendMessage either way.

Too many permission prompts

Every teammate's prompt surfaces in the lead. Pre-approve common commands in your permissions before spawning.

Teammates give up early

Open the teammate, give it more direction, or spawn a replacement. Messaging a teammate that is waiting to retry a failed API call makes it retry immediately. If the lead declares victory too soon, tell it to keep going.

Leftover tmux sessions

tmux ls
tmux kill-session -t <name>

Limitations

• /resume and /rewind do not restore in-process teammates. After resuming, ask the lead to spawn fresh ones.
• Task status can lag when a teammate forgets to mark work done, blocking dependants. Check and nudge.
• Shutdown waits for each teammate's current request or tool call.
• One team per session, scoped to that session.
• Teammates cannot spawn teammates, and the lead cannot be changed.
• An in-process teammate's subagents always run in the foreground; background: true definitions error, and run_in_background: true either errors or runs in the foreground.
• Per-teammate permission modes cannot be set at spawn.
• Split panes need tmux or iTerm2.

Related

• Run agents in parallel
• Create custom subagents
• Cross-session messaging
• Worktrees
• Hooks reference