Claude Code Agent Teams

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

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

	Subagents	Agent Teams
Context	Own context; result returns to caller	Own context; fully independent
Communication	Report to main agent only	Teammates message each other directly
Coordination	Main agent manages all work	Shared task list with self-coordination
Best for	Focused tasks where only result matters	Work needing discussion and challenge
Token cost	Lower (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. Shift+Down cycles between them; Enter views a teammate’s session, 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 "auto" (split panes if already inside tmux, otherwise in-process). Override with teammateMode in ~/.claude/settings.json or claude --teammate-mode in-process.

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.

Recommended sizing

• 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.
• 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, feedback-driven changes expected.

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. Cycle teammates with Shift+Down; press Enter to view a session, 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. End with: “Clean up the team.” Use the lead — never have teammates run cleanup themselves.

Related

• Claude Code Subagents — the in-session counterpart; choose subagents when only the result matters.
• Claude Managed Agents — Anthropic’s hosted long-running agent service.
• Claude Code Hooks — the deterministic quality-gate layer (TeammateIdle, TaskCreated, TaskCompleted).
• Claude Code Scheduled Tasks — /loop and cron tools; pairs with agent teams for long-running work.
• Claude Code Channels — push external events into a session.
• oh-my-claudecode — community 30k-star plugin offering its own multi-agent orchestration on top of native primitives.
• The Advisor Strategy (advisor_20260301) — peer coordination contrasted with hierarchical advisor consultation.
• Claude Agent Hierarchy — When to Use Which

Troubleshooting

Added in the official docs (2026-05-10 sweep):

Teammates not appearing — In in-process mode, press Shift+Down to cycle (they may already be running but not visible). 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 with Shift+Down (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>

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?