Library
Claude Code Documentation (June 2026) · 2 of 15
Claude Code Documentation (June 2026)
ai HIGH

Agent Teams (experimental)

Claude Code Documentation (June 2026) Anthropic
agent-teams teammates coordination task-list hooks experimental

Key Principle

Agent teams are multiple Claude Code instances working together: one team lead (your main session — coordinates, assigns, synthesizes) plus teammates that each run in their own context window and message each other directly through a shared task list + mailbox (Section: Architecture; p. agent-teams). This is the scale-out tier past subagents — it preserves the lead's context while parallelizing, but at a real cost. Experimental, disabled by default.

Why This Matters

Subagents report only to the main agent and return a summarized result (lower token cost); teams let workers share findings, challenge each other, and self-coordinate (higher cost — each teammate is a full, separate Claude instance, so tokens scale roughly linearly with active teammate count). Choose teams only when workers must genuinely talk to each other or you want to interact with individual teammates; otherwise a single session or subagents is cheaper (Section: Subagents vs. agent teams).

Good Examples

Enable (env var in shell or settings.json):

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

Parallel code review with distinct lenses (so coverage doesn't overlap):

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.

Competing-hypotheses debugging (adversarial — fights anchoring):

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.

Plan approval gate (teammate stays read-only until lead approves):

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

Reuse a subagent definition as a teammate role:

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

Display mode (~/.claude/settings.json or --teammate-mode <value>):

{ "teammateMode": "auto" }

Counterpoints

  • Teammates do NOT inherit the lead's /model — you can silently run them on the wrong model. Name a model per spawn or set Default teammate model in /config (Section: Teammates and models).
  • Lead's conversation history does NOT carry over — teammates auto-load project context (CLAUDE.md, MCP, skills) but you must put task-specific details in the spawn prompt (Section: Best practices).
  • Subagent skills/mcpServers frontmatter are NOT applied to teammates; the definition body is appended to the system prompt, tools/model are honored, and SendMessage + task tools are always available (Section: Subagent definitions as teammate roles).
  • Permissions fan out: teammates start in the lead's permission mode — if the lead runs --dangerously-skip-permissions, every teammate does too. Per-teammate modes only changeable after spawn (Section: Permissions).
  • Default mode changed to "in-process" in v2.1.179 (was "auto") — upgraded sessions lose split panes unless set explicitly. Split panes need tmux/iTerm2; not supported in VS Code integrated terminal, Windows Terminal, or Ghostty (Section: Limitations).
  • Avoid file conflicts: two teammates editing the same file overwrite each other — give each its own files. Avoid teams for sequential or many-dependency work.
  • v2.1.181: an idle teammate's row hides after 30s and reappears on its next turn — it stays running and addressable while hidden. Message it by name to bring it back.
  • Limitations: one team per session, no nested teams, lead is fixed (no transfer), no /resume//rewind restore of in-process teammates, no broadcast (one message per recipient).
  • Removed (v2.1.178): TeamCreate, TeamDelete tools. Agent team_name input is ignored; team_name in TaskCreated/TaskCompleted/TeammateIdle payloads is deprecated.

Key Commands & Config

Enable:  CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1   (settings.json env or shell)
Display: teammateMode  in-process(default v2.1.179) | auto | tmux
         claude --teammate-mode <value>           tmux -CC in iTerm2 (recommended)

Quality-gate hooks (exit code 2 = block action + send feedback):

  • TeammateIdle — teammate about to go idle; exit 2 keeps it working.
  • TaskCreated — exit 2 prevents creation + sends feedback.
  • TaskCompleted — exit 2 prevents completion + sends feedback.

Task states: pending, in progress, completed; pending-with-dependencies can't be claimed until deps complete. Lead assigns or teammates self-claim next unblocked task; file locking arbitrates simultaneous claims; completing a dependency auto-unblocks dependents.

Storage (team name = session- + first 8 chars of session ID):

~/.claude/teams/{team-name}/config.json   Runtime state — removed when session ends; do not hand-edit
~/.claude/tasks/{team-name}/              Task list — persists locally, never uploaded

Retention follows cleanupPeriodDays (same as session transcripts). In-process keys: ↑/↓ select, Enter open/message, Escape interrupt, x stop teammate, Ctrl+T toggle task list.

Orphaned tmux cleanup:

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

Rules of Thumb

  • Start with 3–5 teammates (~5–6 tasks each); three focused often beat five scattered. Scale only when work genuinely benefits from simultaneity.
  • New to teams → start with research/review tasks (PR review, library research, bug investigation) — no parallel-implementation coordination headaches.
  • Make the lead wait: "Wait for your teammates to complete their tasks before proceeding."
  • Give plan-approval criteria ("only approve plans with test coverage"); without them the lead approves on its own judgment.
  • Pre-approve common operations before spawning — teammate permission prompts bubble up to the lead.

Related References