Agent Teams

The Problem

Spec Kit solves "the agent built the wrong thing." Worktrees solve "I can only run one agent at a time." But once you have more than two agents working in parallel, you hit a new problem: coordination. Subagents can only report back to the main session. They can't talk to each other, challenge each other's assumptions, or pick up each other's slack. You become the message bus, and your attention becomes the bottleneck.

Agent Teams removes the bottleneck. Teammates communicate directly, claim tasks from a shared list, and only surface to you when they need input or when work is done.

What You Get

A first-class multi-agent mode inside Claude Code, shipped with Opus 4.6 (February 2026). One session becomes the team lead. It spawns teammates, assigns tasks, and synthesizes results. Each teammate runs in its own Claude Code instance with its own context window, loads your CLAUDE.md, MCP servers, and skills, and receives messages from other teammates automatically through a mailbox.

Two display modes:

• In-process: every teammate runs inside one terminal. Shift+Down cycles through them, Ctrl+T toggles the task list. No setup required.
• Split panes: each teammate gets its own pane. Requires tmux or iTerm2 with the it2 CLI.

Teams are stored in ~/.claude/teams/{team-name}/config.json with a shared task list in ~/.claude/tasks/{team-name}/. Task claiming uses file locking so two teammates never grab the same task.

How to Run It

Claude Code v2.1.32 or later is required. Enable the experimental feature in your settings:

1# settings.json
2{
3  "env": {
4    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
5  }
6}

Then ask the lead to create a team in plain English. It decides team size, spawns teammates, and assigns work:

1Create an agent team to review PR #142. Spawn three reviewers:
2- One focused on security implications
3- One checking performance impact
4- One validating test coverage
5Have them each review and report findings.

Or use it for investigation when you have multiple competing hypotheses:

1Users report the app exits after one message instead of staying connected.
2Spawn 5 teammates to investigate different hypotheses. Have them talk to
3each other to try to disprove each other's theories, like a scientific
4debate. Update the findings doc with whatever consensus emerges.

When you are done:

1Clean up the team

Why This Matters for Senior Teams

• Parallel review without context collisions.Security, performance, and test coverage each get a dedicated reviewer with a fresh context window. No single reviewer drifting toward their favorite class of issues.
• Competing hypotheses beat sequential investigation.Anchoring kills single-agent debugging. Five teammates each defending a theory and actively trying to falsify the others converges on the real root cause much faster.
• Cross-layer features ship in one pass.Frontend, backend, and tests each owned by a different teammate, coordinating directly instead of through you.
• Reusable roles via subagent definitions.Define security-reviewer or test-runner once as a subagent, reuse the same definition as a teammate. One source of truth for both delegation patterns.
• Hooks enforce quality gates.TaskCreated, TaskCompleted, and TeammateIdle hooks can block a task from being marked done until CI passes, types check, or coverage holds.

Where It Fits in the Stack

• Plan with Spec Kit.Each /speckit.tasks output is a ready-made task list for a team.
• Isolate with worktrees (Superset, Vibe Kanban).Run a team per worktree, one per feature, no file collisions across teams.
• Review with sentry-code-review or ai-tools.Assign the review skill to a dedicated teammate once implementation teammates finish.
• Require plan approval for risky work.Tell the lead to keep a teammate in read-only plan mode until it approves the approach — works well for schema changes and auth.

When Not to Use It

Agent Teams use significantly more tokens than a single session — each teammate is a full Claude instance. Skip it for:

• Sequential work where each step depends on the last.
• Changes concentrated in one file (teammates will overwrite each other).
• Routine tasks where a single session or a subagent is cheaper and faster.

Start with 3–5 teammates, 5–6 tasks each. Scale up only when the work genuinely benefits from parallelism. Three focused teammates beat five scattered ones.

Known Limitations (Experimental)

• /resume and /rewind do not restore in-process teammates — tell the lead to respawn them.
• Task status can lag; occasionally you need to nudge a teammate to mark a task complete.
• One team per session, no nested teams, lead is fixed for the team's lifetime.
• Split-pane mode needs tmux or iTerm2. Not supported in VS Code integrated terminal, Windows Terminal, or Ghostty.

Source

• Agent Teams documentationcode.claude.com (opens in a new tab)