claudekit / guides / agent-teams
[ Guide · Advanced · 15 min ]

Agent Teams

published · updated

How to coordinate multiple Claude Code instances as a team that shares a task list and communicates directly. Covers in-process mode, the iTerm2 + tmux split-pane setup, use cases, and known limitations.

What are agent teams?

Agent teams let you coordinate multiple Claude Code instances working together. One session acts as the team lead, coordinates work, and synthesizes results, while teammates work independently in their own context windows and message each other directly.

Agent teams require Claude Code 2.1.32 or later (where they first shipped as a research preview). Check your version with claude --version. This guide follows the official docs as of October 2026 (v2.1.314); cleanup, the default display mode, and panel navigation have changed since the early releases. Agent teams are experimental and disabled by default, with known limitations around session resumption, task coordination, and shutdown behavior.

Unlike subagents, which work within a single session and return a result to the caller, you can also talk to any teammate directly without going through the lead.

Official docs: Orchestrate teams of Claude Code sessions — code.claude.com/docs/en/agent-teams

Compare with subagents

SubagentsAgent teams
ContextOwn context window; results return to the callerOwn context window; fully independent
CommunicationReturn a result to the callerTeammates message each other directly
CoordinationMain agent manages all workSelf-coordination through messages, plus a shared task list
Best forFocused tasks where only the result mattersComplex work requiring discussion and collaboration
Token costLower — results summarized back to main contextHigher — each teammate is a separate Claude instance

Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.

Enable agent teams

Set the CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS environment variable to 1, either in your shell environment or through ~/.claude/settings.json.

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

Enabling agent teams also changes ordinary delegation. While agent teams are enabled, a subagent that Claude names launches as a teammate, so teams can form even when you didn’t ask for one. Spawning teammates also requires an interactive session: in non-interactive mode with -p, including Agent SDK sessions, Claude doesn’t spawn teammates, and a named subagent runs as an ordinary subagent.

Start your first team

After enabling agent teams, describe the task and the teammates you want in natural language. There’s no team setup step: since 2.1.178, every session has one implicit team, and Claude spawns teammates directly. This example works well because the three roles are independent and can explore the problem without waiting on each other:

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 may sometimes use subagents instead of creating a team. Subagents appear in the same agent panel as teammates, so the panel alone doesn’t confirm a team formed. If that happens, ask again and explicitly request an agent team.

The lead’s terminal lists teammates in the agent panel below the prompt input. Use the up and down arrows to select a teammate, then press Enter to open its transcript and message it directly.

The team’s shared directories are cleaned up automatically when the session ends, so there’s no separate cleanup step.

Display modes — in-process vs split panes

Agent teams support two display modes:

  • In-process — all teammates run inside your main terminal. Use the up and down arrow keys in the agent panel to select a teammate, then press Enter to view it and type to message it directly. Works in any terminal, no extra setup required.
  • Split panes — each teammate gets its own pane. You can see everyone’s output at once and click into a pane to interact directly. Requires tmux or iTerm2.

The default is "in-process". The other values:

  • "auto" — split panes when you’re already running inside a tmux session, or when your terminal is iTerm2 with the it2 CLI installed (or tmux available), falling back to in-process otherwise.
  • "tmux" — enables split-pane mode and auto-detects whether to use tmux or iTerm2 based on your terminal.
  • "iterm2" — uses iTerm2 native split panes explicitly through the it2 CLI (added in 2.1.186). Shows an error with the install command if it2 is missing.

To override the default, set teammateMode in ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

To set the mode for a single session, pass it as a flag. The --teammate-mode flag is experimental and doesn’t appear in claude --help.

claude --teammate-mode auto

Split-pane mode requires either tmux or iTerm2 with the it2 CLI. Split panes are not supported in VS Code’s integrated terminal, Windows Terminal, or Ghostty.

iTerm2 + tmux setup (the simplest combination)

Split panes require either tmux on its own or iTerm2 with the it2 CLI — not both. The official docs suggest tmux -CC in iTerm2 as the entrypoint into tmux, and that path doesn’t need the it2 CLI or the iTerm2 Python API at all. tmux has known limitations on certain operating systems and traditionally works best on macOS.

1. Install tmux

brew install tmux

Verify it’s on your PATH:

which tmux

2. Set teammateMode

With the default "in-process", teammates don’t open in split panes even inside tmux. Set "teammateMode" to "auto" or "tmux" in ~/.claude/settings.json:

{
  "teammateMode": "tmux"
}

3. Launch iTerm2 with tmux -CC

Open a fresh iTerm2 window and start a tmux control-mode session:

tmux -CC

iTerm2 renders the tmux session as native windows and tabs. Run Claude Code from inside this session.

4. Verify with a team

Create an agent team and confirm each teammate opens in its own iTerm2 pane. If split panes don’t open, check your teammateMode value and run which tmux to confirm tmux is on your PATH.

Agent team teammates opened as separate split panes inside iTerm2 after launching with tmux -CC

Without tmux: iTerm2 standalone

If you’d rather not install tmux, iTerm2 native split panes work through a separate path. This path is the only one that needs the it2 CLI and the Python API enabled; set teammateMode to "iterm2" or "auto".

  1. Enable iTerm2 → Settings → General → Magic → Enable Python API

  2. Install the it2 CLI with uv (recommended) or pip:

    uv tool install it2

    If you don’t have uv, pip install it2 works too. it2 requires macOS with iTerm2 3.3.0 or later and Python 3.10+.

For most users, the tmux + tmux -CC route above is simpler, so try it first.

Agent panel shortcuts (in-process)

Useful when you stay inside the main terminal:

ShortcutAction
Up / Down arrowsSelect a teammate
EnterOpen the selected teammate’s transcript and message it directly
EscapeClear the selection. While viewing a teammate’s transcript, interrupts that teammate’s current turn
xStop the selected teammate
Ctrl+TToggle the task list

Once every agent in the panel is idle, idle rows hide after 30 seconds; the teammate stays running and addressable while hidden. When more than three teammates are idle, the extra rows collapse into a single N idle agents row that Enter expands.

Control your team

Tell the lead what you want in natural language. It handles team coordination, task assignment, and delegation based on your instructions.

Specify teammates and models

Claude decides the number of teammates based on the task, or you can specify exactly what you want:

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

Claude Code picks each teammate’s model from the first of these that applies:

  1. The model your spawn prompt names for that teammate.
  2. For a teammate spawned from a subagent definition, the definition’s model, where inherit selects the lead’s model.
  3. CLAUDE_CODE_SUBAGENT_MODEL, when it’s set to anything other than inherit.
  4. The lead’s current model.

teammateDefaultModel was removed in v2.1.234; Claude Code ignores a leftover value. Name the model in your prompt instead. A teammate’s model and fast mode are fixed when it spawns.

Have teammates plan before implementing

For complex or risky tasks, you can have teammates plan before implementing. A teammate that Claude spawns while the lead is in plan mode works in read-only plan mode until its plan is ready. Switch the lead into plan mode first, then ask for the teammate:

Spawn an architect teammate to refactor the authentication module.

When that teammate finishes planning, it sends a plan approval request to the lead. If you haven’t changed that teammate’s permission mode since it was spawned, Claude Code approves the plan as soon as the request arrives, without the lead reviewing it — so this isn’t a way to gate plans on criteria you write in the prompt. The teammate’s edits and commands still go through the usual permission prompts.

If you put a running in-process teammate in plan mode by pressing Shift+Tab while viewing its session, the lead reviews that run’s plan instead, and approves it or sends it back for revision.

Talk to teammates directly

Each teammate is a full, independent Claude Code session. You can message any teammate directly to give additional instructions, ask follow-up questions, or redirect their approach.

  • In-process — use the up and down arrow keys in the agent panel to select a teammate, then press Enter to view its session and type to send it a message. Press x on a selected teammate to stop it. Press Ctrl+T to toggle the task list.
  • Split panes — click into a teammate’s pane to interact with their session directly. Each teammate has a full view of their own terminal.

While you’re viewing an in-process teammate, plain text and skills go to that teammate, and built-in commands go to the lead’s session. /compact, /clear, and /rewind act on the lead’s conversation, so Claude Code asks you to confirm first; /model and /fast don’t run from this view.

Assign and claim tasks

The shared task list coordinates work across the team. Tasks have three states — pending, in progress, completed — and can depend on other tasks. A task with unfinished dependencies shows as blocked; teammates don’t self-claim a blocked task, but you or the lead can still assign it. When a dependency completes, Claude Code unblocks the dependent tasks automatically.

  • Lead assigns — tell the lead which task to give to which teammate
  • Self-claim — after finishing a task, a teammate picks up the next unassigned, unblocked task on its own

Task claiming uses file locking to prevent race conditions when multiple teammates try to claim the same task simultaneously.

Shut down teammates

To gracefully end a teammate’s session, refer to it by name:

Ask the researcher teammate to shut down

The lead sends a shutdown request. The teammate can approve, exiting gracefully, or reject with an explanation.

There’s no separate cleanup step. Version 2.1.178 removed the TeamCreate and TeamDelete tools, and the team’s shared directories are cleaned up automatically when the session ends. See “How agent teams work” below for which directories are removed and which stay on disk.

How agent teams work

An agent team consists of four components:

ComponentRole
Team leadThe main Claude Code session that spawns teammates and coordinates work
TeammatesSeparate Claude Code instances that each work on assigned tasks
Task listShared list of work items that teammates claim and complete
MailboxMessaging system for communication between agents

Teams and tasks are stored locally under a session-derived name (session- followed by the first eight characters of the session ID):

  • Team config: ~/.claude/teams/{team-name}/config.json — removed when the session ends.
  • Task list: ~/.claude/tasks/{team-name}/ — stays on disk after the session ends; set cleanupPeriodDays to change how long it’s kept.

The team config holds runtime state such as session IDs and tmux pane IDs, so don’t edit it by hand or pre-author it — your changes are overwritten on the next state update. To define reusable teammate roles, use subagent definitions instead.

Each teammate has its own context window. When spawned, a teammate loads the same project context as a regular session — CLAUDE.md, MCP servers, and skills — but the lead’s conversation history does not carry over. Include task-specific details in the spawn prompt.

Use subagent definitions for teammates

When spawning a teammate, you can reference a subagent type from the project, user, managed, or plugin subagent scope. This lets you define a role once, such as a security-reviewer or test-runner, and reuse it both as a delegated subagent and as an agent team teammate.

Spawn a teammate using the security-reviewer agent type to audit the auth module.

Which parts of the definition apply depends on the teammate’s display mode:

  • tools and model — applied in either display mode. For an in-process teammate, Claude Code adds SendMessage and the Task tools to the list.
  • Body — for an in-process teammate, appended to its default system prompt as additional instructions. For a split-pane teammate, used in place of its default system prompt.
  • skills — not applied in either display mode. The teammate loads skills from your project and user settings.
  • mcpServers — applied for a split-pane teammate. An in-process teammate ignores the field and loads MCP servers from your project and user settings.

So skills attached only to a subagent definition won’t take effect for teammates, and MCP servers attached only there won’t take effect for in-process teammates.

Use case examples

Run a parallel code review

A single reviewer tends to gravitate toward one type of issue at a time. Splitting review criteria into independent domains means security, performance, and test coverage all get thorough attention simultaneously:

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.

Investigate with competing hypotheses

When the root cause is unclear, a single agent tends to find one plausible explanation and stop looking. Making teammates explicitly adversarial forces them to challenge each other’s theories rather than anchor on the first one.

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.

Sequential investigation suffers from anchoring: once one theory is explored, subsequent investigation is biased toward it. With multiple independent investigators actively trying to disprove each other, the theory that survives is much more likely to be the actual root cause.

Enforce quality gates with hooks

Use hooks to enforce rules when teammates finish work or tasks are created or completed. Exiting with code 2 sends feedback and blocks the action.

HookFires whenEffect of exit code 2
TeammateIdleA teammate is about to go idleSends feedback and keeps the teammate working
TaskCreatedA task is being createdPrevents creation, sends feedback
TaskCompletedA task is being marked completePrevents completion, sends feedback

Best practices

  • Give teammates enough context — teammates load CLAUDE.md, MCP servers, and skills automatically, but they don’t inherit the lead’s conversation history. Include task-specific details (file paths, libraries used, reporting format) in the spawn prompt.
  • Start with 3–5 teammates — token cost scales linearly and coordination overhead grows. Keep 5–6 tasks per teammate.
  • Size tasks appropriately — too small means coordination overhead exceeds the benefit; too large means teammates work too long without check-ins. Aim for self-contained units like a function, a test file, or a review.
  • Avoid file conflicts — two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files.
  • Monitor and steer — don’t let a team run unattended for too long. Redirect approaches that aren’t working and synthesize findings as they come in.
  • Start with research and review — if you’re new to agent teams, start with PR reviews, library research, or bug investigations. These show the value of parallel exploration without the coordination challenges of parallel implementation.

Known limitations

Agent teams are experimental. Current limitations to be aware of:

  • No session resumption with in-process teammates — /resume and /rewind do not restore in-process teammates. After resuming, the lead may attempt to message teammates that no longer exist. Tell the lead to spawn new ones.
  • Task status can lag — teammates sometimes fail to mark tasks as completed, blocking dependent tasks. If a task appears stuck, check whether the work is actually done and update the task status manually or tell the lead to nudge the teammate.
  • Shutdown can be slow — teammates finish their current request or tool call before shutting down.
  • One team per session — a session has exactly one team, scoped to that session. You can’t create additional named teams or share a team across sessions.
  • No nested teams — teammates cannot spawn their own teammates. Only the lead can manage the team.
  • No background subagents from in-process teammates — an in-process teammate’s own subagents run in the foreground. Claude Code returns an error when a teammate spawns a subagent whose definition sets background: true.
  • Lead is fixed — the main session is the lead for its lifetime. You can’t promote a teammate to lead or transfer leadership.
  • Permissions set at spawn — teammates start with the lead’s permission mode, except dontAsk mode, which they don’t inherit. You can change individual modes after spawning, but you can’t set per-teammate modes at spawn time.
  • Split panes require tmux or iTerm2 — the default in-process mode works in any terminal. Split panes are not supported in VS Code’s integrated terminal, Windows Terminal, or Ghostty.

Troubleshooting

Teammates not appearing

  • In in-process mode, teammates appear in the agent panel below the prompt input. Use the up and down arrow keys to select one, then press Enter to view it.

  • A teammate row that disappeared after sitting idle has been hidden, not stopped. Send the teammate a message by name to bring it back.

  • Check that the task is complex enough to warrant a team — Claude decides whether to spawn teammates based on the task.

  • If you explicitly requested split panes, check that teammateMode isn’t "in-process" and that tmux is on your PATH:

    which tmux
  • If you’re using iTerm2 standalone (without tmux), verify the it2 CLI is installed and the Python API is enabled.

Claude spawns teammates instead of subagents

While agent teams are enabled, a subagent that Claude names launches as a teammate. To make named subagents launch as subagents again, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 0. Claude Code reapplies settings-file env values to the running session when you save, so you don’t need a new session. Project, local, or managed settings that set it to 1 still win over user settings.

Too many permission prompts

Teammate permission requests bubble up to the lead, which can create friction. Pre-approve common operations in your permission settings before spawning teammates.

Teammates stopping on errors

Teammates may stop after encountering errors instead of recovering. Check their output, then either give them additional instructions directly or spawn a replacement teammate.

Orphaned tmux sessions

If a tmux session persists after the Claude Code session ends, it may not have been fully cleaned up. List sessions and end the one created by the team:

tmux ls
tmux kill-session -t <session-name>

Next steps

§ 14

Frequently Asked Questions

frequently asked
§ 14.1
What's the difference between agent teams and subagents?
Subagents work within a single session and return a result to the caller. Agent teams are separate Claude Code instances: teammates message each other directly through a mailbox and coordinate through a shared task list. Pick teams when work needs discussion and collaboration; pick subagents when only the result matters.
§ 14.2
How do I enable agent teams?
Agent teams require Claude Code 2.1.32 or later, and you enable them by setting the `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` environment variable in your shell or under `env` in `~/.claude/settings.json`. Enabling agent teams also changes ordinary delegation: a subagent that Claude names launches as a teammate, so teams can form even when you didn't ask for one.
§ 14.3
How do I set up split-pane mode with iTerm2 + tmux?
Install tmux with `brew install tmux`, launch it inside iTerm2 with `tmux -CC`, and set `"teammateMode": "auto"` (or `"tmux"`) in `~/.claude/settings.json`. The default is `"in-process"`, so without that setting teammates won't open in split panes even inside tmux. The it2 CLI and iTerm2 Python API are only needed if you skip tmux and use iTerm2 native split panes.
§ 14.4
How many teammates should I have?
Start with 3–5 teammates for most workflows. Having 5–6 tasks per teammate keeps everyone productive and lets the lead reassign work if someone gets stuck. Token cost scales linearly with active teammates and coordination overhead grows, so only scale up when work genuinely benefits from running in parallel.
§ 14.5
When are agent teams most effective?
Use them for work where parallel exploration adds value: research and review across different lenses, new modules where teammates own separate pieces, debugging with competing hypotheses, and cross-layer changes that span frontend, backend, and tests.