Claude Code Agent Teams: A Practical Introduction

When Anthropic shipped Claude Opus 4.6 in early February 2026, the model got the headlines. But the feature that matters most for anyone interested in AI teams was tucked into Claude Code: agent teams, a research-preview capability that lets one Claude Code session spawn and coordinate several other Claude Code sessions working in parallel. It is the closest thing yet to watching a small AI engineering team form, divide up work, argue about findings, and report back — all inside your terminal.

This is a practical introduction: what agent teams actually is, how the pieces fit together, where it genuinely helps, where it doesn't, and how to turn it on.

What agent teams is (and isn't)

Agent teams is experimental multi-agent orchestration built directly into Claude Code. One session — the one you're typing into — becomes the team lead. On your instruction, it spawns teammates: each one a full, independent Claude Code instance with its own context window, its own tool access, and its own view of your project.

Two things distinguish this from earlier "spawn a helper" patterns:

1. Teammates talk to each other, not just to the lead. Communication is peer-to-peer.
2. Work is coordinated through a shared task list that teammates can claim from on their own, rather than the lead micromanaging every step.

The feature is explicitly experimental. It's disabled by default, hidden behind an environment variable, and the official documentation lists known limitations up front. Treat it as a preview of a working style, not a finished product.

It's also worth being clear about what it is not: agent teams is an interactive development-workflow tool. It runs inside your terminal session, expects you to watch and steer, and its teams live and die with the session. It is not a production agent framework — there's no deployment story, no durable orchestration, no API for running teams as a service. If you're looking for that, see our comparison of multi-agent frameworks.

How it works: four moving parts

An agent team has four components, per the docs:

The mailbox

Each agent gets a mailbox — implemented as a JSON file under ~/.claude/teams/{team-name}/inboxes/ — and any teammate can message any other teammate by name. This sounds like plumbing, but it's the architecturally interesting part: findings, objections, and requests flow directly between agents instead of being routed through the lead. The lead doesn't have to poll for updates either; messages are delivered automatically, and idle teammates notify the lead when they finish.

The shared task list

The lead breaks work into tasks with three states (pending, in progress, completed) and optional dependencies — a task that depends on unfinished work can't be claimed until the blocker completes. Teammates can be assigned tasks explicitly, or they can self-claim: finish one task, pick up the next unassigned, unblocked one. Claiming uses file locking so two teammates can't grab the same task in a race.

This is what makes the system feel like a team rather than a dispatcher with workers. You can give the lead fifteen independent tasks and three teammates, and the work distributes itself.

What teammates know

A freshly spawned teammate loads the same project context a normal session would — CLAUDE.md, MCP servers, skills — plus the spawn prompt the lead wrote for it. What it does not get is the lead's conversation history. The practical consequence: put task-specific context into the spawn prompt, because the teammate wasn't in the room when you explained the problem.

Agent teams vs. subagents

Claude Code has had subagents for a while, and the distinction matters:

• Subagents run within your session, do a focused job, and report results back to the caller. They never talk to each other. Cheaper, simpler, right answer for "go look this up and tell me what you found."
• Agent teams are fully independent sessions that share a task list and message each other. More expensive, more capable, right answer for work that benefits from discussion and parallel ownership.

A useful rule from the docs: use subagents when only the result matters; use a team when the workers need to coordinate.

What it's good for

The pattern shines where parallel exploration adds real value:

• Parallel code review. Spawn three reviewers with different lenses — security, performance, test coverage — over the same PR. Each applies one filter thoroughly instead of one agent skimming for everything at once.
• Debugging with competing hypotheses. The documentation's most interesting example: spawn several investigators, give each a different theory, and tell them to actively try to disprove each other like a scientific debate. Sequential investigation anchors on the first plausible explanation; adversarial parallel investigation is more likely to surface the real root cause.
• New modules and features. Work that splits along clean boundaries — one teammate on the API, one on the frontend, one on tests — where nobody edits the same file.
• Research and exploration. Have teammates evaluate a library, an architecture question, or a migration path from different angles, then synthesize.

And what it's not good for: sequential work, tasks with heavy interdependencies, and anything where multiple agents would edit the same files (two teammates writing one file ends in overwrites). For those, a single session or subagents are both cheaper and better.

A real data point: Claude Code Review

The clearest evidence that this pattern does real work came in March 2026, when Anthropic launched Claude Code Review, an automated PR reviewer built on a multi-agent architecture: parallel specialized reviewer agents examine each pull request, followed by a verification pass that filters false positives before findings are posted as inline comments.

The number Anthropic reported from internal use: the share of pull requests receiving substantive review comments rose from 16% to 54% after deployment. The usual caveat applies — that's Anthropic measuring Anthropic, on its own codebase — but it's a concrete, production-shaped result from the same "several specialized agents in parallel, then synthesize" pattern that agent teams gives you interactively.

Getting started

Agent teams is off by default. Enable it via environment variable, either in your shell or in settings.json:

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

Then just describe the team you want in natural language. The docs' example prompt is a good template:

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

The lead populates the task list, spawns the teammates, and synthesizes when they finish. A few things worth knowing early:

• Display modes. By default everything runs in-process: teammates appear in an agent panel below your prompt, and you can arrow-key onto one, press Enter to open its transcript, and message it directly. If you prefer each teammate in its own pane, split-pane mode is available via tmux or iTerm2 ("teammateMode": "auto" in ~/.claude/settings.json).
• You can talk to any teammate directly. Each is a full session — redirect its approach, ask follow-ups, or stop it, without going through the lead.
• Plan approval. For riskier work, ask for teammates to require plan approval: the teammate works read-only until the lead approves its plan, and you can give the lead approval criteria ("only approve plans that include test coverage").
• Quality gates. Hooks like TeammateIdle and TaskCompleted can block a teammate from going idle or a task from closing until your checks pass.

The docs' sizing advice is sensible: start with 3–5 teammates and roughly 5–6 tasks each, give each teammate ownership of distinct files, and start with read-only work — review and research — before trying parallel implementation.

Honest caveats

This is a research preview, and it behaves like one:

• Token cost scales linearly. Every teammate is a separate Claude instance with its own context window. A five-agent team burns tokens at something like five sessions' rate. For research and review the trade is often worth it; for routine tasks it isn't.
• No session resumption for in-process teammates. /resume won't restore them; the lead may try to message teammates that no longer exist.
• Task status can lag. Teammates sometimes fail to mark tasks complete, which blocks dependents until you nudge.
• Structural limits. One team per session, no nested teams (teammates can't spawn teammates), and the lead is fixed for the session's lifetime.
• It needs supervision. The docs are candid: letting a team run unattended for long stretches increases the risk of wasted effort. This is a tool you steer, not one you schedule.

Where this fits in an AI-team stack

Agent teams is the most accessible way today to feel what multi-agent collaboration is like: real parallelism, real peer-to-peer coordination, with you in the loop. If that working style clicks, the natural next questions are what a longer-lived AI employee looks like, and how to go from an interactive team in your terminal to a durable one — which is where production multi-agent frameworks and shared tool layers like MCP come in. For the bigger picture of assembling agents into a functioning department, start with our guide to building your AI team in 2026.

We write about this stuff as it ships. If you're building toward an AI team of your own, follow BuildYour.Group or join the early-access waitlist — we'd like to build alongside you.