Agent Teams

Why Agent Teams Exist

Subagents solve context isolation: delegate a task to a worker, get a distilled result back, keep your main context clean. Each subagent only reports to the lead — workers never talk to each other.

Agent Teams solve a different problem: inter-agent collaboration. When the task genuinely benefits from multiple independent perspectives debating, challenging, or building on each other’s findings, routing everything through a central lead becomes a bottleneck. Team members communicate directly via a shared mailbox and a shared task list. The lead coordinates, but teammates can self-organize.

The key distinction:

Subagents report results to the lead
Team members talk to each other

Hub-and-Spoke vs Mesh

graph TD subgraph Subagents["Subagents — Hub and Spoke"] Lead1([Lead]) --> SA([Worker A]) Lead1 --> SB([Worker B]) Lead1 --> SC([Worker C]) SA -.results.-> Lead1 SB -.results.-> Lead1 SC -.results.-> Lead1 end subgraph Teams["Agent Teams — Mesh"] T1([Agent A]) <-->|SendMessage| T2([Agent B]) T2 <-->|SendMessage| T3([Agent C]) T1 <-->|SendMessage| T3 TL[(Shared\nTask List)] T1 & T2 & T3 --> TL end style Lead1 fill:#0D2840,stroke:#1A4A70,color:#E8ECF1 style SA fill:#0D2E1A,stroke:#1A5030,color:#E8ECF1 style SB fill:#0D2E1A,stroke:#1A5030,color:#E8ECF1 style SC fill:#0D2E1A,stroke:#1A5030,color:#E8ECF1 style T1 fill:#25153D,stroke:#4A2878,color:#E8ECF1 style T2 fill:#25153D,stroke:#4A2878,color:#E8ECF1 style T3 fill:#25153D,stroke:#4A2878,color:#E8ECF1 style TL fill:#3A3010,stroke:#6B5820,color:#E8ECF1

Subagents vs Agent Teams

	Subagents	Agent Teams
Communication	Results → lead only	Peer `SendMessage` between any members
Coordination	Lead manages all work	Self-coordinating via shared task list
Context	Isolated per subtask, returns summary	Each teammate: independent full session
Token cost	Lower — results distilled back	Higher — each teammate is a full Claude instance
Session resumption	Supported	Not supported for in-process teammates
Best for	Focused parallel workers	Research with competing hypotheses, cross-layer features

Use subagents when you need quick focused workers that only need to report back. Use agent teams when teammates need to share findings, challenge each other’s conclusions, or coordinate distributed ownership.

When to Use Agent Teams

Agent teams earn their token cost when:

Competing hypotheses: multiple teammates each investigate a different root cause and actively try to disprove the others — the surviving theory is more trustworthy
Parallel review with distinct lenses: security, performance, and test coverage reviewers working simultaneously on the same PR
Cross-layer features: frontend, backend, and test suite each owned by a different teammate with no file conflicts
Context limit pressure: parallel subagents are hitting context limits — teams give each worker its own full context window

Avoid agent teams for sequential tasks, same-file edits, or simple work where coordination overhead exceeds the benefit.

Enable Agent Teams

Add to ~/.claude/settings.json or your project’s .claude/settings.json:

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

Or set the environment variable directly:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Start a Team

Once enabled, describe the task and the team structure in plain language. Claude creates the team, spawns teammates, and coordinates based on your prompt:

I'm designing a CLI tool to track TODO comments across a codebase.
Create an agent team: one teammate on UX, one on technical architecture,
one playing devil's advocate. Have them share findings and challenge each other.

For a parallel code review:

Create an agent team to review PR #142. Three reviewers:
- Security implications
- Performance impact
- Test coverage
Have each reviewer report findings to the lead.

For competing bug hypotheses:

Users report the app exits after one message.
Spawn 5 teammates to investigate different hypotheses. Have them actively
try to disprove each other's theories. Update a findings doc with
whatever consensus emerges.

How Coordination Works

Shared Task List

All team members share a task list. The lead creates tasks; teammates claim and complete them. Tasks can express dependencies — a blocked task cannot be claimed until its dependencies are resolved. The system handles unblocking automatically when a dependency completes.

Task states: pending → in-progress → completed

File locking prevents two teammates from claiming the same task simultaneously.

SendMessage

Teammates communicate directly without routing through the lead:

SendMessage(to: "teammate-name", type: "message", ...) — direct peer message
SendMessage(type: "broadcast") — sends to all teammates; use sparingly, costs scale with team size

The lead does not need to poll — messages are delivered automatically.

Idle Notifications

When a teammate finishes and goes idle, it automatically notifies the lead. The lead can reassign remaining tasks or shut the teammate down.

Architecture

Display Modes

Mode	How it works	Requirements
in-process (default)	All teammates run in your main terminal. `Shift+Down` cycles through them.	Any terminal
tmux	Each teammate gets its own pane. See everyone’s output at once.	tmux or iTerm2

The default is auto: uses split panes if you are already inside a tmux session, in-process otherwise.

Override globally in ~/.claude.json:

{
  "teammateMode": "in-process"
}

Override for a single session:

claude --teammate-mode in-process

Note: split-pane mode does not work in VS Code’s integrated terminal, Windows Terminal, or Ghostty.

Team Configuration Storage

Teams and tasks are stored locally — not in your project directory:

~/.claude/teams/{team-name}/config.json   # runtime state: session IDs, pane IDs
~/.claude/tasks/{team-name}/              # task list files

Claude generates and updates these automatically. Do not edit config.json by hand — it is overwritten on every state update.

To define reusable teammate roles (tools, model, system prompt), use subagent definitions and reference them by name when spawning:

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

The teammate inherits that subagent’s tools allowlist and model. SendMessage and task management tools are always available to teammates even when tools restricts other tools.

Plan Approval for Teammates

For risky tasks, require teammates to plan before implementing:

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

The teammate works read-only until the lead approves its plan. If rejected, the teammate revises and resubmits. Give the lead criteria in your prompt to influence its judgment: “only approve plans that include test coverage”.

Cleanup

When done, ask the lead to clean up:

Clean up the team

This removes shared team resources. The lead checks for active teammates first — shut them down before cleanup, or cleanup will fail.

Always use the lead to clean up. Teammates running cleanup may leave resources in an inconsistent state.

Best Practices

Team size: 3–5 teammates for most workflows. Beyond 5, coordination overhead and token cost increase faster than throughput improves. Start with 3 focused teammates rather than 5 scattered ones.

Task sizing: 5–15 minutes each — small enough to parallelize meaningfully, large enough to be a real deliverable (a function, a test file, a review). Having 5–6 tasks per teammate keeps everyone productive.

Avoid file conflicts by assigning different files or directories to different teammates. Two teammates editing the same file causes overwrites.

Give context at spawn time — teammates load project CLAUDE.md, MCP servers, and skills, but they do not inherit the lead’s conversation history. Include task-specific details in the spawn prompt.

Monitor and steer — check in on progress, redirect teammates that are going in circles, and synthesize findings as they come in. Letting a team run unattended for too long risks wasted tokens on incorrect approaches.

Start with research tasks — if you are new to agent teams, try a PR review or codebase investigation before parallel implementation. Research tasks have clear boundaries and show the value of parallel exploration without file-conflict risk.

Current Limitations

Limitation	Detail
No session resumption	`/resume` and `/rewind` do not restore in-process teammates after a session ends
Task status lag	Teammates sometimes fail to mark tasks complete; check manually if a dependent task appears stuck
One team per session	Clean up the current team before starting a new one
No nested teams	Teammates cannot spawn sub-teams or their own teammates
Fixed leadership	The session that creates the team is lead for its lifetime
Permissions set at spawn	All teammates start with the lead’s permission mode; cannot set per-teammate modes at spawn time
Slow shutdown	Teammates finish their current tool call before shutting down
Split panes: terminal restrictions	tmux or iTerm2 required; not available in VS Code integrated terminal, Windows Terminal, or Ghostty

For current status, see the official Agent Teams documentation.

See also: Subagents · Git Worktrees · Parallel Sessions