Claude Code Agent Teams: Setup and Orchestration Guide

Claude Code agent teams are an experimental feature that lets one lead session coordinate multiple teammate agents, each running in its own context window, sharing a task list and messaging each other directly. They are disabled by default: you turn them on by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your settings or environment, then describe the task and the teammates you want in plain language. This guide explains what agent teams are, how they differ from subagents, how to enable and run one, and the orchestration patterns that hold up, all verified against Anthropic's agent teams documentation as of July 2026.

What Are Claude Code Agent Teams?

An agent team is a group of Claude Code sessions working together, with one session acting as the team lead. The lead spawns teammates, each a full independent Claude Code instance with its own context window, then coordinates work by populating a shared task list and synthesizing results when teammates finish. Teammates communicate directly with each other through a mailbox, so they can share findings, challenge each other, and claim tasks without routing everything through the lead.

This is a genuine, documented Claude Code capability, not a prompt trick. It shipped as an experimental feature in v2.1.178, and the team state lives locally: team config in ~/.claude/teams/{team-name}/config.json and the task list in ~/.claude/tasks/{team-name}/, where the team name is session- followed by the first eight characters of the session ID. Because it is experimental, expect rough edges and read the limitations before you rely on it.

Agent Teams vs Subagents

The difference between agent teams and subagents is communication: teammates message each other and self-coordinate, while subagents only report results back to the main agent and never talk among themselves. That single distinction decides which one you want. Use subagents for focused, fire-and-forget workers where only the result matters; use agent teams when the workers need to discuss, disagree, and converge.

There is a third option worth naming so you pick the right tool. Background agents run many full sessions in parallel that you monitor from one screen, and Git worktrees let you run separate Claude Code sessions yourself with no automated coordination. Agent teams sit in the middle: automated coordination, with inter-agent messaging that subagents lack.

How to Enable and Start a Team

Agent teams are disabled by default, so the first step is setting the experimental flag. Add it to the env block of your settings.json, or export it in your shell:

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

With the flag set, you do not create a team manually. You describe the work and the teammates you want, and the lead spawns them. A prompt that works well gives each teammate an independent lens so they do not wait on each other:

I'm designing a CLI tool that tracks TODO comments across a codebase.
Spawn three teammates to explore this from different angles: one on UX,
one on technical architecture, one playing devil's advocate.

By default teammates run in-process in your main terminal, listed in an agent panel below the prompt. Use the up and down arrows to select a teammate and Enter to open its transcript and message it directly. If you want each teammate in its own pane, set teammateMode to auto in ~/.claude/settings.json or pass claude --teammate-mode auto, which requires tmux or iTerm2. Split-pane mode is not supported in the VS Code integrated terminal, Windows Terminal, or Ghostty.

You can also name teammates, pin their model, and require plan approval. Telling the lead "Use Sonnet for each teammate" or "Require plan approval before they make any changes" keeps cost and risk in check. Teammates do not inherit the lead's /model selection unless you set the default teammate model in /config.

Orchestration Patterns That Work

Agent teams pay off when parallel exploration adds real value, and Anthropic's docs highlight four patterns where they beat a single session. The common thread is that each teammate owns an independent slice, so they rarely block one another.

• Parallel code review. Spawn one teammate for security, one for performance, one for test coverage on the same PR. A single reviewer tends to fixate on one issue class; splitting the lenses covers all three at once and the lead synthesizes the findings.
• Competing hypotheses. For a murky bug, spawn several teammates to investigate different theories and have them message each other to disprove each other's ideas, like a scientific debate. The theory that survives adversarial challenge is far more likely to be the real root cause.
• New modules or features. Give each teammate a separate file set so they build in parallel without overwriting each other. Two teammates editing the same file is the fastest way to lose work.
• Cross-layer coordination. Assign frontend, backend, and tests to different teammates for a change that spans all three, then let the shared task list unblock dependent work as each layer lands.

Start small. If you are new to teams, use research and review tasks that have clear boundaries and do not write code, then scale up. Anthropic recommends 3 to 5 teammates for most workflows, with roughly 5 to 6 tasks per teammate; three focused teammates usually outperform five scattered ones. If the lead starts doing the work itself instead of delegating, tell it to wait for its teammates to finish.

Reuse Subagent Definitions as Roles

You can define a role once as a subagent and reuse it as a teammate, which is where agent teams and subagents connect. When you spawn a teammate, reference an existing subagent type by name and the teammate honors that definition's tools allowlist and model, with the definition's body appended to the teammate's system prompt.

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

This makes your .claude/agents/ directory a shared library of reusable roles for both delegated subagents and team teammates. Our best Claude Code subagents guide ranks the roles worth defining first, and the Everything Claude Code guide covers where agent files live and the frontmatter fields they support. One caveat: the skills and mcpServers frontmatter fields do not apply when a definition runs as a teammate; teammates load skills and MCP servers from your project and user settings instead.

Teammates also respect quality gates. Hooks like TeammateIdle, TaskCreated, and TaskCompleted can send feedback and keep an agent working when it tries to stop or complete prematurely, the same Claude Code hooks mechanism you use elsewhere.

Limitations and Tradeoffs

The biggest cost of agent teams is tokens. Each teammate is a separate Claude instance with its own context window, and Anthropic's cost documentation measures roughly 7x the token usage of a single session when teammates run in plan mode. Keep teams small, use Sonnet for teammates, keep spawn prompts focused, and shut teammates down when their work is done, because each active teammate keeps consuming tokens until it exits or the session ends.

The feature is also experimental, with real rough edges as of July 2026. Sessions do not resume in-process teammates, so /resume and /rewind leave the lead messaging teammates that no longer exist. There is exactly one team per session, teammates cannot spawn their own teammates, and the lead role is fixed for the session's lifetime. Task status can lag when a teammate forgets to mark work complete, which blocks dependent tasks until you nudge it. For sequential tasks, same-file edits, or work with many dependencies, a single session or plain subagents is the better and cheaper choice.

Related Guides

• Best Claude Code Subagents in 2026: Ranked and Explained
• Claude Agent Teams: How to Structure Multi-Agent Work
• Everything Claude Code: The Complete Guide
• Claude Code Best Practices in 2026