Jonathon's AI Wiki

Claude Code Agent Teams

13 min read

Source: Anthropic official docs — Agent Teams + earlier ai-research (web research, 2026-04-11) Type: Product Feature (experimental / research preview) Product: Claude Code Requires: Claude Code v2.1.32 or later (significant changes in v2.1.178–v2.1.181)

An experimental Claude Code feature that coordinates multiple Claude Code instances working together as a team. One session is the lead; the others are teammates, each with its own full context window and permission set. Unlike subagents — which run inside a single session and only report back — teammates communicate with each other directly, share a task list, and can be addressed individually without going through the lead.

How it works

  • One session is the team lead — coordinates work, assigns tasks, synthesizes results.
  • Teammates are separate Claude Code instances. Each loads its own CLAUDE.md, MCP servers, and skills at spawn. The lead’s conversation history does not carry over.
  • A shared task list lets teammates claim work via file-locked atomic claiming. Tasks have three states (pending, in progress, completed) and can declare dependencies that auto-unblock.
  • A mailbox routes messages: any teammate can send to any other by name; messages arrive automatically without polling.
  • The lead can assign explicitly (“give the security task to teammate-A”) or teammates can self-claim the next available task.

Agent Teams vs Subagents

SubagentsAgent Teams
ContextOwn context; result returns to callerOwn context; fully independent
CommunicationReport to main agent onlyTeammates message each other directly
CoordinationMain agent manages all workShared task list with self-coordination
Best forFocused tasks where only result mattersWork needing discussion and challenge
Token costLower (results summarized back)Higher (each teammate is a full session)

Enabling

Disabled by default. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in shell env or in settings.json:

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

Display modes

  • In-process — all teammates run in the main terminal. Up/Down arrows select a teammate; Enter views their session; x stops the selected teammate; Esc interrupts; Ctrl+T toggles the task list. Works in any terminal.
  • Split panes — each teammate gets its own pane. Requires tmux or iTerm2 with the it2 CLI. Not supported in VS Code’s integrated terminal, Windows Terminal, or Ghostty.
  • Default is "in-process" (changed from "auto" at v2.1.179). Override with teammateMode in ~/.claude/settings.json or claude --teammate-mode <mode> per-session.

Available teammateMode values:

ValueDescription
"in-process"Default since v2.1.179. All teammates in main terminal.
"auto"Auto-detect: use split panes if tmux or iTerm2 available, else in-process.
"tmux"Use tmux split panes explicitly.
"iterm2"Use iTerm2 native split panes explicitly (v2.1.186+). Requires the it2 CLI — shows an error with the install command if it2 is missing. The setup prompt offering to install it2 or fall back to tmux appears under "auto" or "tmux" when your terminal is iTerm2 and tmux is available as a fallback.

Effort inheritance

Teammates inherit the lead’s effort level. In split-pane mode, this applies from v2.1.186; earlier versions did not pass the lead’s session effort to split-pane teammates.

Plan approval gates

For complex or risky teammate work, the lead can require a plan-approval handshake: the teammate works in read-only plan mode until the lead approves. If rejected, the teammate revises and resubmits. Influence the lead’s judgment by stating criteria in your spawn prompt (“only approve plans that include test coverage”).

Hooks for quality gates

Three hook events fire around teammate work:

  • TeammateIdle — runs when a teammate is about to go idle. Exit code 2 sends feedback and keeps it working.
  • TaskCreated — runs when a task is being created. Exit code 2 prevents creation.
  • TaskCompleted — runs when a task is being marked complete. Exit code 2 prevents completion and sends feedback.

See Claude Code Hooks for the full hook system.

Subagent definitions as teammate roles

Spawn a teammate using a subagent type from any scope (project, user, plugin, CLI-defined). The teammate honors the definition’s tools allowlist and model; the body becomes additional system-prompt instructions (not a replacement). SendMessage and task-management tools are always available even if tools restricts other tools. Note: the subagent’s skills and mcpServers frontmatter fields are NOT applied when running as a teammate — those are loaded from project/user settings.

Storage

  • Team config: ~/.claude/teams/{team-name}/config.json — runtime state (session IDs, tmux pane IDs). Don’t pre-author or hand-edit; overwritten on every state update.
  • Task list: ~/.claude/tasks/{team-name}/
  • Project-level config (e.g., .claude/teams/teams.json) is not recognized.
  • 3-5 teammates for most workflows. Token cost scales linearly per teammate; coordination overhead grows superlinearly.
  • 5-6 tasks per teammate keeps everyone productive without excessive context switching.
  • Three focused teammates often outperform five scattered ones.

Use case examples (from Anthropic docs)

  • Parallel code review — one reviewer per filter (security, performance, test coverage). Each works the same PR through a different lens; lead synthesizes.
  • Competing hypotheses for debugging — five teammates investigate different theories, talk to each other to disprove, converge on what survives. Sequential investigation suffers from anchoring; adversarial structure fights it.
  • Cross-layer coordination — frontend, backend, and tests each owned by a different teammate.

Key Takeaways

  • Agent Teams is the collaborative tier above subagents — teammates talk to each other and can be addressed directly, not just through the lead.
  • Best for research/review, debugging with competing hypotheses, and cross-layer changes — work where parallel exploration adds real value.
  • Each teammate is a full Claude session: own context, tools, permissions, task claims. Token cost scales linearly with team size.
  • The shared task list (with file-locked claiming and dependency tracking) is the core coordination mechanism.
  • Hooks (TeammateIdle, TaskCreated, TaskCompleted) let you enforce quality gates deterministically. Note: team_name in hook payloads is deprecated as of v2.1.178+.
  • Subagent definitions can be reused as teammate roles, but their skills and mcpServers frontmatter is dropped when running as a teammate.
  • Limitations to plan around: no /resume or /rewind for in-process teammates, no nested teams, lead is fixed for the team’s lifetime, permissions set at spawn, one team per session.
  • Available since Claude Code v2.1.32. Experimental — flag-gated. v2.1.178+: setup/cleanup is automatic (TeamCreate/TeamDelete removed). v2.1.179: default mode changed from auto to in-process. v2.1.181: idle teammate row hides after 30 seconds. v2.1.186: explicit "iterm2" display mode added; effort inheritance in split-pane mode. v2.1.198: API error notification to lead; message-wake-on-retry for stuck in-process teammates. v2.1.199: idle row stays while any teammate is working (no longer hides mid-team); 3+ idle rows collapse; /model//fast notice when viewing teammate. v2.1.207: mailbox validation and malformed-entry self-healing — invalid entries stripped on read; valid messages delivered normally.

Try It

  1. Add "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" under "env" in ~/.claude/settings.json.
  2. Start with a research-style task that has clear boundaries: “Create an agent team to review PR #142. Spawn three reviewers — security, performance, test coverage. Have each report findings.”
  3. Navigate teammates with Up/Down arrows to select; press Enter to view a session, x to stop a teammate, Esc to interrupt, Ctrl+T to toggle the task list.
  4. When the lead starts implementing instead of waiting, prompt: “Wait for your teammates to complete their tasks before proceeding.”
  5. Cleanup is now automatic (v2.1.178+) — the team tears down after the task. To clean up manually, tell the lead to wrap up.

Troubleshooting

Added/updated in the official docs (2026-06-21 sweep):

Teammates not appearing — In in-process mode, use Up/Down arrows to select teammates (they may already be running but not visible; idle rows hide after 30 seconds in v2.1.181+). Verify tmux is installed (which tmux) for split-pane mode. For iTerm2, verify it2 CLI installed and Python API enabled in preferences. Check task complexity — Claude decides whether to spawn teammates.

Too many permission prompts — Pre-approve common operations in permission settings before spawning teammates to reduce interruptions during a run.

Teammates stopping on errors — Check output by navigating with Up/Down arrows (in-process) or click pane (split). Give additional instructions directly or spawn a replacement teammate to continue the work. As of v2.1.198, a message from you or another teammate immediately wakes an in-process teammate waiting to retry a failed API request — send it a message to trigger immediate retry instead of waiting for the backoff delay.

Lead shuts down before work is done — Tell it to keep going explicitly. To prevent this pattern, include “wait for teammates to finish before proceeding” in the spawn instruction.

Orphaned tmux sessions — If a tmux session persists after the team ends:

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

Recent additions (2026-08-07 weekly sweep)

200-subagent-per-session spawn cap removed (v2.1.224)

The CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION hard cap (introduced v2.1.212, default 200) no longer applies. Long-running sessions that were silently refusing new subagent spawns when the cap was reached are no longer blocked.

The concurrency cap (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, default 20) and depth cap (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, default 3) still apply — total slots in flight and nesting depth remain bounded. The removal targets the per-session total count, not the in-flight or nesting controls.

Cross-session SendMessage between machines (v2.1.224)

Claude Code sessions can now message each other across machines via SendMessage + ListAgents (macOS and Linux). For an agent team, a lead or teammate can surface results to a session running in a different terminal or on a different machine — not just within the same process or daemon.

Safety gate: SendMessage calls go through the permission classifier before dispatch (v2.1.222). Messages sent to a session running with bypassed permissions are held for human approval (crossSessionInbound setting); messages to other sessions auto-deliver.

Source: ai-research/claude-code-docs-changelog-2026-08-07.md. Full detail in What’s New — Week 32.

Recent additions (2026-07-19 watchlist sweep)

v2.1.207 — Mailbox validation and malformed-entry recovery

Claude Code now validates every entry when reading an agent’s mailbox file (~/.claude/teams/{team-name}/inboxes/{agent-name}.json). Entries that don’t match the message format are reported as errors and removed from the file; valid messages continue to be delivered normally.

Before v2.1.207, a single malformed mailbox entry caused a repeated error every second and blocked all message delivery for that mailbox until you deleted the file manually. This self-healing behavior is particularly important for long-running agent teams where a temporary write failure, crash mid-write, or encoding error in one message would previously block the entire mailbox until manual intervention.

Recent additions (2026-07-05 watchlist sweep)

Changes in the official agent-teams docs at v2.1.198–v2.1.199:

  • v2.1.199 — Idle row stays while any teammate is working. Previously (v2.1.181–v2.1.198), an idle teammate’s row hid 30 seconds after its own turn ended, even while other teammates were still active. As of v2.1.199, an idle row stays in the panel while any teammate or subagent is still working, so you can select idle teammates to review their transcripts or send them more work. Once every agent in the panel is idle, rows hide after 30 seconds as before and reappear on the teammate’s next turn.
  • v2.1.199 — 3+ idle collapse. When more than three teammates are idle simultaneously, rows beyond the first three collapse into a single N idle agents row. Select it and press Enter to expand; Esc to collapse. Working, failed, and currently-viewed teammates always keep their own rows.
  • v2.1.199 — /model and /fast notice when viewing a teammate. These commands only affect the lead’s settings (a teammate’s model and fast mode are fixed at spawn). As of v2.1.199, typing either command while viewing a teammate shows a notice that the change applies to the lead. Earlier versions applied it silently. Note: /effort still applies to the viewed teammate’s later turns, because teammates follow the lead’s effort level.
  • v2.1.198 — API error notification to lead. A teammate whose turn ends on an API error now notifies the lead with the error text, instead of appearing to finish normally. Previously this was a silent failure from the lead’s perspective.
  • v2.1.198 — Message-wake-on-retry. A message from the lead or another teammate immediately wakes an in-process teammate that is waiting to retry a failed API request, so it retries immediately instead of waiting for the full retry delay. Useful for unblocking a stuck teammate without waiting for its backoff timer.
  • No background subagents from in-process teammates (new Limitation). An in-process teammate’s own subagents run in the foreground. Asking for a background subagent returns an error because a teammate’s background work can’t outlive the lead’s process.

Recent additions (2026-06-28 watchlist sweep)

Changes documented in the official agent-teams docs at v2.1.186:

  • Explicit "iterm2" display mode (v2.1.186) — Set teammateMode: "iterm2" (or --teammate-mode iterm2) to use iTerm2 native split panes without relying on auto-detection. Requires the it2 CLI (available at github.com/mkusaka/it2 and via Homebrew). If it2 is missing, Claude Code shows an error with the install command. The setup prompt offering to install it2 or fall back to tmux appears under "auto" or "tmux" mode when your terminal is iTerm2 and tmux is available as a fallback. The Python API must be enabled in iTerm2 → Settings → General → Magic → Enable Python API.
  • Effort inheritance in split-pane mode (v2.1.186) — Teammates now inherit the lead’s effort level in split-pane ("tmux" and "iterm2") mode. Earlier versions passed effort to in-process teammates but not to split-pane teammates; v2.1.186 closes this gap.

Recent additions (2026-06-21 watchlist sweep)

Changes documented in the official agent-teams docs across v2.1.178–v2.1.181:

  • v2.1.178 — TeamCreate/TeamDelete tools removed. Spawning a teammate no longer requires a setup step; cleanup is automatic when the team ends.
  • v2.1.179 — Default teammateMode changed from "auto" to "in-process". Users who relied on the auto-detection of tmux for split panes must now set --teammate-mode tmux explicitly.
  • v2.1.181 — Idle teammate’s row hides in the TUI after 30 seconds. The row reappears when the teammate becomes active again. Use Up/Down arrows to navigate; the teammate is still running even when the row is hidden.
  • Navigation updated — Shift+Down (old) → Up/Down arrows to select a teammate. x key stops the selected teammate.
  • team_name deprecated in TeammateIdle, TaskCreated, and TaskCompleted hook payloads. Migrate hooks that access this field.

Open Questions

  • What is the practical hard ceiling on team size before coordination overhead dominates? Anthropic recommends 3-5 but does not name an absolute maximum.
  • How does a teammate’s task-claim race resolve in adversarial scenarios (e.g., two teammates with stale task-list views)? File locking is named, semantics aren’t fully spelled out.
  • When does Agent Teams move out of research preview? No published timeline.
  • Will nested teams (teammate spawning its own team) ever be supported, or is the single-tier model permanent?

Graph View

Backlinks