Claude Code Agent Teams: When Agents Talk to Each Other (2026)

Five agents spent forty minutes arguing about why an app kept exiting after one message, and the theory that survived was the one nobody started with. That's the use case Anthropic's own documentation leads with, and it's a fair description of what Claude Code agent teams are actually for. You already know a single agent tends to find one plausible explanation and stop looking. Teams attack that directly by making several independent investigators try to disprove each other. Below: how to turn the feature on, the one architectural difference that separates teammates from subagents, how to spawn and steer a team, what it costs, and the limitations you will hit in the first hour.

Turning It On (It's Off by Default)

Agent teams are experimental and disabled by default. Enable them by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, in your shell environment or in settings.json:

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

Without that variable, no team is set up at session start, no team directories are written, and Claude won't spawn or propose teammates at all. If you asked for a team and got subagents instead, this variable is the first thing to check.

The setup story got simpler in v2.1.178. Before that release you asked Claude to create and name a team first, using TeamCreate and TeamDelete tools. Both are gone. Now a team forms when the first teammate spawns, and cleanup happens automatically when the session exits. Older tutorials that walk you through creating a team by name are describing a version that no longer exists.

Teammates vs Subagents: The Difference Is the Mailbox

Both let you parallelize, and choosing between them comes down to one question: do the workers need to talk to each other?

A subagent is a function call that happens to be intelligent: you send a task, you get a result, and nothing else crosses the boundary. A teammate is a colleague. It can read the shared task list, claim the next unblocked item without being told, and send a message to another teammate by name. You can also open its transcript and talk to it directly rather than routing instructions through the lead.

Reach for subagents when only the result matters and you want the cheaper option. Reach for a team when the workers need to share findings and challenge each other, which is a much narrower set of tasks than the excitement around multi-agent systems suggests.

Spawning Your First Team

There's no command. You describe the task and the teammates you want in plain language, and Claude spawns them:

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.

Claude populates the shared task list, spawns a teammate per perspective, has them explore, and synthesizes findings when they finish. It may sometimes use subagents instead; since subagents appear in the same agent panel, the panel alone doesn't confirm a team formed. Ask again and explicitly request an agent team if that happens.

You can be specific about size and model: "Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate." Teammates don't inherit the lead's /model selection by default, and you change that with Default teammate model in /config, where picking Default (leader's model) makes them follow the lead. Teammates do inherit the lead's effort level.

For risky work, require a plan first: "Spawn an architect teammate to refactor the authentication module. Require plan approval before they make any changes." The teammate works in read-only plan mode until the lead approves, and a rejected plan sends it back to revise and resubmit. The lead makes those calls autonomously, so give it criteria in your prompt if you care about the standard, such as "only approve plans that include test coverage."

You can also reuse role definitions you already have. Mention a subagent type by name and the teammate honors that definition's tools allowlist and model, with the body appended to its system prompt: "Spawn a teammate using the security-reviewer agent type to audit the auth module." Two frontmatter fields don't carry over, and this catches people out: skills and mcpServers in a subagent definition are ignored when it runs as a teammate. Teammates load skills and MCP servers from your project and user settings like a regular session, which is a good reason to keep shared skills at the project level rather than pinned to one agent definition.

In-Process or Split Panes

Two display modes, and the default changed recently enough that upgraded sessions surprise people.

In-process is the default: every teammate runs in your main terminal. Use up and down arrows in the agent panel below the prompt to select one, press Enter to open its transcript and message it, Escape to interrupt its turn, x to stop it, and Ctrl+T to toggle the task list. This works in any terminal with no extra setup.

Split panes gives each teammate its own pane and requires tmux or iTerm2 with the it2 CLI. Set it in ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

Before v2.1.179 the default was "auto", so sessions that previously opened split panes now stay in one terminal unless you set the mode explicitly. Split-pane mode isn't supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.

One behavior in the panel confuses everyone once. An idle teammate's row hides 30 seconds after the whole panel goes idle, and when more than three are idle the surplus rows collapse into a single 2 idle agents row. A hidden row means hidden, not stopped: the teammate is still running and addressable, and messaging it by name brings the row back.

While you're viewing a teammate, plain text and skills go to that teammate but built-in commands still run in the lead's session. A teammate's model and fast mode are fixed at spawn, so /model and /fast only change the lead. /effort does apply to the viewed teammate's later turns.

The Shared Task List and How Work Gets Claimed

The shared task list is the coordination substrate. Tasks have three states, pending, in progress, and completed, and can depend on other tasks; a pending task with unresolved dependencies can't be claimed until those complete. Claude Code unblocks dependents automatically when a teammate finishes their prerequisite.

Work gets distributed two ways. The lead assigns tasks explicitly when you tell it who should do what, or a teammate self-claims the next unassigned, unblocked task after finishing its current one. Claiming uses file locking so two teammates can't grab the same task in a race.

Underneath, each agent's mailbox is a JSON file at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json, with team config at ~/.claude/teams/{team-name}/config.json and the task list under ~/.claude/tasks/{team-name}/. The team name is session- plus the first eight characters of the session ID. Don't hand-edit the config: it holds runtime state like session IDs and pane IDs and gets overwritten on the next state update. The config directory is removed when the session ends; the task list persists locally so resumed sessions keep their tasks.

If you want hard gates rather than suggestions, three hook events exist for teams. TeammateIdle runs when a teammate is about to go idle, TaskCreated when a task is being created, and TaskCompleted when one is being marked done. Exit with code 2 from any of them to block the transition and send feedback, which is how you enforce "tests pass before a task counts as complete."

What It Costs in Tokens

Agent teams use significantly more tokens than a single session, and the reason is structural rather than incidental. A subagent's work gets summarized back into one context; a teammate's context window is its own and stays its own. Usage scales with the number of active teammates.

Anthropic's own sizing guidance is the useful part: start with three to five teammates for most workflows, and aim for five to six tasks per teammate to keep everyone busy without excessive context switching. Fifteen independent tasks suggests about three teammates. Beyond a point, more teammates stop speeding things up proportionally while coordination overhead keeps rising, and the documentation is blunt that three focused teammates often outperform five scattered ones.

Nadia, who leads a four-person platform team, ran a team of six on a cross-service refactor and found two of them idling on dependencies for most of the run while still holding open context. She now sizes teams from the dependency graph rather than the file count, which is the same instinct as sizing a sprint. Working out whether that spend makes sense for you starts with the pricing model, because teams are the one Claude Code feature where token cost is a planning input rather than a footnote.

The Limitations You'll Hit First

This is experimental software and the constraints are real, so here they are in the order you're likely to meet them.

No session resumption with in-process teammates. /resume and /rewind don't restore them. After resuming, the lead may try to message teammates that no longer exist, and the fix is telling it to spawn new ones.

Task status lags. Teammates sometimes fail to mark tasks complete, which blocks anything depending on them. If a task looks stuck, check whether the work is actually done and update the status yourself or nudge the teammate through the lead.

The lead can finish early. It may decide the team is done before all tasks are. It may also start doing tasks itself instead of delegating; "wait for your teammates to complete their tasks before proceeding" fixes that one.

Structural limits you can't work around. One team per session, scoped to that session. No nested teams, since only the lead can manage the team. The lead is fixed for the session's lifetime with no promoting a teammate. And all teammates start with the lead's permission mode: if the lead runs with --dangerously-skip-permissions, so does everyone. You can change individual modes after spawning but not at spawn time, which is worth pairing with the permissions model before you run a team on anything sensitive.

On that last point, one safeguard is well designed. When one agent messages another, Claude Code tells the recipient the message came from another Claude session rather than from you. A teammate can't approve a permission prompt or give consent on your behalf, and a teammate denied an action can't relay it to another teammate to get around the check. In auto mode the classifier treats a relayed approval claim as untrusted input and reviews every inter-agent message before delivery.

Start With an Investigation, Not a Refactor

The first team you run should produce a document, not a diff. Reviewing a pull request from three angles, researching a library, or chasing a bug with competing hypotheses all have clear boundaries, no file conflicts, and an output you can judge in five minutes. Parallel implementation is where the coordination problems live: two teammates editing the same file means overwrites, so the work has to be split by file ownership before it's split by teammate. Get one investigation under your belt, watch how the mailbox and task list actually behave, and only then point a team at code. The failure mode isn't that teams don't work; it's spending six teammates' worth of tokens on something one session would have done better.

Browse next: Claude Code Subagents (2026) | Claude Code Review (2026) | Claude Code Hooks (2026) | Claude Code Memory (2026)

Back to Blog