Jonathon's AI Wiki

Claude Code Agent Teams

8 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: "tmux" in ~/.claude/settings.json or claude --teammate-mode tmux for split panes.

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.

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.

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-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