Claude Code agent teams: several sessions working together

Who this is for and what you will get

Agent teams suit work that splits into independent pieces, such as a code review from several angles or a hard bug investigated through competing theories. This feature is experimental and disabled by default. By the end you will know how to enable it, describe a team in plain language, switch display modes, manage teammates, and recognize the cases where a team is not worth its cost.^[1]

When to use a team and when to use subagents

Teams fit four kinds of work: research and review, new modules or features, debugging with competing hypotheses, and cross-layer changes that touch frontend, backend and tests.^[1]

Teams add coordination overhead and use significantly more tokens than a single session. For sequential tasks, edits to the same file, or work with many dependencies, a single session or subagents are more effective.^[1]

A subagent returns its result to the caller. Teammates share a task list and message each other directly. Subagent results are summarized back into the main context, which makes them cheaper.^[1]

Turn the feature on

Set the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1, in your shell or in settings.json:

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

Enabling it changes ordinary delegation too. Claude can name a subagent, and while teams are enabled, a named subagent launches as a teammate. A team can therefore form even if you never asked for one.^[1] Teammates cannot be spawned in non-interactive mode with -p, including Agent SDK sessions.^[1]

Describe the team in plain language

After enabling the feature, describe the task and the teammates you want. Claude spawns them and coordinates the work. A prompt might look like this:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

Claude can sometimes choose subagents rather than a team. Both appear in the same agent panel, so the panel alone does not prove a team formed. If you got subagents, ask again and name an agent team explicitly.^[1]

Manage the teammates

The agent panel below the prompt input lists the teammates. Use the up and down arrow keys to select one, press Enter to open its transcript and message it, and press Escape to clear the selection.^[1]

There are two display modes. In-process mode runs every teammate inside your main terminal and works in any terminal. Split-pane mode gives each teammate its own pane and requires tmux or iTerm2.^[1] For iTerm2, install the it2 command-line tool and enable the Python API under iTerm2 > Settings > General > Magic > Enable Python API.^[1]

To choose automatically, set teammateMode to "auto" in ~/.claude/settings.json. Teammates then open in split panes inside tmux or iTerm2 and run in-process elsewhere:

{
  "teammateMode": "auto"
}

For a single session, pass the flag, for example claude --teammate-mode auto. The flag is experimental and does not show up in claude --help:

claude --teammate-mode auto

In-process or split panes

In-process mode needs no extra setup and works in any terminal. In split-pane mode each teammate gets its own pane, and you can click into one to work with that teammate directly, but tmux or iTerm2 must be installed first.^[1]

A session holds exactly one team, and that team belongs to the session it was created in. Teammates cannot spawn teammates of their own.^[1]

Tasks and messages

The lead names every teammate when it spawns it. Any teammate can message any other by name. To reach everyone, send one message per recipient.^[1]

Tasks are pending, in progress or completed. A task can depend on others and shows as blocked until they finish. Teammates do not claim blocked tasks. The lead can assign work directly, or a teammate that finishes its own work can claim the next unassigned, unblocked task. Claiming uses file locking, so two teammates cannot grab the same task.^[1]

To shut a teammate down cleanly, ask for it by name:

Ask the researcher teammate to shut down

The teammate can approve the request and exit, or reject it with an explanation.^[1]

Teammates do not inherit the lead's conversation history. They load CLAUDE.md, MCP servers and skills as a regular session does, and they receive the spawn prompt from the lead.^[1] A teammate's model comes from the first applicable source: the model named in the spawn prompt, then the subagent definition's model, then CLAUDE_CODE_SUBAGENT_MODEL if it is set to something other than inherit, and finally the lead's current model.^[1]

Cost, size and file conflicts

Each teammate has its own context window, so token use grows with the number of active teammates. Research, review and new feature work usually justify the extra spend. For routine tasks a single session is cheaper.^[1]

Teams need not be large. The guidance is to start with 3-5 teammates for most workflows, since three focused teammates often outperform five scattered ones.^[1] If two teammates edit the same file, their changes overwrite each other, so split the work so that each teammate owns different files.^[1]

Example uses

To review a pull request from several angles, ask for three teammates, each with a different focus:

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

When the cause of a bug is unclear, have teammates challenge one another's theories:

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

Turn it off and clean up

If named subagents start launching as teammates when you did not want that, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 0 in settings.json:

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

Claude Code rereads the variable when it spawns a subagent, so a new session is not needed.^[1]

Limits and common problems

• Teammates vanish after a resume. /resume and /rewind do not restore in-process teammates.^[1]
• One team per session. A session holds exactly one team, and teammates cannot spawn teammates of their own.^[1]
• Split panes need tmux or iTerm2. The default in-process mode runs in any terminal.^[1]

Next step

The full details on display modes, teammate permissions and the known limitations are in Anthropic's Claude Code documentation for agent teams.^[1]