Claude Code Agent Teams: Setup, Controls, and Limits

Claude Code agent teams let one Claude Code session act as a team lead that spawns several other full Claude Code sessions, called teammates. Each teammate gets its own context window, the team shares a task list, and teammates message each other directly instead of reporting only to the lead.

Three things to know before you try it:

• It's experimental and off by default. You turn it on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.
• It costs more. Every teammate is a separate Claude instance, so token usage grows with team size.
• It's not the default answer to "I want parallel work." Anthropic's own docs say to check whether subagents do the job first.

This guide covers how to enable Claude Code teams of agents, how the lead, task list, and mailbox fit together, the keyboard controls, display modes, the current limitations, and a quick subagents-vs-teams comparison.

What Claude Code agent teams are

Anthropic's agent teams documentation describes a team as four parts:

The part that makes it a team rather than a batch of helpers is communication. Teammates can share findings, challenge each other, and coordinate on their own. You can also talk to any teammate yourself without going through the lead.

What a teammate starts with. When it spawns, a teammate loads the same project context as a normal session: your CLAUDE.md, MCP servers, and skills. It also gets the spawn prompt the lead wrote. It does not get the lead's conversation history. Anything you discussed with the lead before spawning has to be restated in the spawn prompt, or written into CLAUDE.md.

How to enable agent teams

Set the environment variable to 1, either in your shell or in settings.json:

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

Without that variable, the docs say no team is set up at session start, no team directories are written, and Claude doesn't spawn or propose teammates.

Two side effects are easy to miss:

1. Named subagents become teammates. While teams are enabled, a subagent that Claude gives a name to launches as a teammate. Claude sometimes names subagents on its own, so a team can form even when you didn't ask for one, and Claude Code doesn't ask you to confirm the launch. If you'd rather keep plain subagents, set the variable to 0. Saving the settings file applies the change to the running session.
2. Interactive sessions only. In non-interactive mode with -p, including Agent SDK sessions, Claude doesn't spawn teammates. A named subagent just runs as a normal subagent.

Starting your first team

There's no special command. You describe the task and the teammates you want in plain language, and the lead does the rest. The docs use this kind of prompt:

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 fills the shared task list, spawns a teammate per role, lets them work, and pulls the findings together when they finish.

Check that a team actually formed. Claude may use subagents instead, and subagents show up in the same agent panel as teammates. If you wanted a team and got subagents, ask again and request an agent team explicitly.

You can also be specific about size and model: "Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate." When your prompt doesn't name a model, Claude Code falls back to the teammate's subagent definition, then the CLAUDE_CODE_SUBAGENT_MODEL variable, then the lead's model.

Reuse a role you already defined. If you have a subagent file like security-reviewer in .claude/agents/, you can say "Spawn a teammate using the security-reviewer agent type." The teammate picks up that definition's tools and model, and its body as instructions. Its skills field is not applied; teammates load skills from your project and user settings.

The shared task list and messaging

Tasks. The lead creates tasks and teammates work through them. Each task is pending, in progress, or completed, and a task can depend on others. A pending task with unfinished dependencies can't be claimed until they're done. When a teammate completes a task, the dependent ones unblock automatically.

Work gets handed out two ways:

• Lead assigns: you tell the lead which task goes to which teammate.
• Self-claim: a teammate that finishes picks up the next unassigned, unblocked task on its own. Claiming uses file locking, so two teammates can't grab the same task.

Messages. Teammates message each other by name, and messages arrive automatically, so the lead doesn't poll. There's no broadcast: to reach everyone, an agent sends one message per recipient. When a teammate finishes and goes idle, it notifies the lead and includes its final answer. If you want names you can reference later, tell the lead what to call each teammate when you spawn them.

Safety between agents. When one agent messages another, Claude Code tells the recipient the message came from another Claude session, not from you. A teammate can't approve a permission prompt on your behalf, and teammate permission prompts surface in the lead session for you to answer.

Quality gates. Three hooks are built for teams: TeammateIdle, TaskCreated, and TaskCompleted. Exiting with code 2 from any of them sends feedback and blocks the step, for example keeping a teammate working or refusing to mark a task done until tests pass. Our Claude Code hooks guide covers how hook scripts work.

Display modes and keyboard controls

Agent teams support two display modes:

You pick the mode with the teammateMode setting in ~/.claude/settings.json. The values are "in-process", "auto" (split panes when you're already inside tmux or iTerm2 with it2, in-process otherwise), "tmux", and "iterm2". For one session, pass claude --teammate-mode auto. That flag is experimental and doesn't appear in claude --help.

Split panes aren't supported in VS Code's integrated terminal, Windows Terminal, or Ghostty.

In in-process mode, the agent panel is where you steer:

One gotcha: while you're viewing a teammate, plain text goes to that teammate, but built-in commands go to the lead. /compact, /clear, and /rewind ask for confirmation first, since they act on the lead's conversation.

To end a teammate, ask by name: "Ask the researcher teammate to shut down." It can accept or decline with an explanation.

Token costs and team size

The docs are blunt: agent teams use significantly more tokens than a single session, and usage scales with the number of active teammates. Anthropic's costs guide gives four ways to keep it under control:

• Use Sonnet for teammates. It balances capability and cost for coordination work.
• Keep teams small. Token usage is roughly proportional to team size.
• Keep spawn prompts focused. Everything in the spawn prompt adds to each teammate's context from the start.
• Shut teammates down when they're done. An active teammate keeps consuming tokens until it exits or the session ends.

On size, the recommendation is to start with 3 to 5 teammates. Even with 15 independent tasks, 3 teammates is a good starting point, and having 5 or 6 tasks per teammate keeps everyone busy. Tasks should be self-contained units with a clear deliverable: a function, a test file, a review.

Two more habits from the same page:

• Avoid file conflicts. Two teammates editing the same file leads to overwrites. Give each one its own set of files.
• Start with research and review. Reviewing a PR or investigating a bug shows the value of parallel work without the coordination problems of parallel implementation.

If the lead starts doing the work itself, tell it: "Wait for your teammates to complete their tasks before proceeding."

Current limitations

Anthropic lists these as known limitations of the experimental feature:

• No session resumption for in-process teammates. /resume and /rewind don't restore them. After resuming, the lead may message teammates that no longer exist; tell it to spawn new ones.
• Task status can lag. A teammate sometimes forgets to mark a task complete, which blocks dependent tasks.
• Shutdown can be slow. Teammates finish their current request or tool call first.
• One team per session. You can't create extra named teams or share a team across sessions.
• No nested teams. Teammates can't spawn their own teammates.
• The lead is fixed. You can't promote a teammate or hand over leadership.
• Permissions are set at spawn. Teammates start with the lead's permission mode. You can change one afterwards, but not at spawn time.

There's also no project-level team config. A file like .claude/teams/teams.json in your repo is treated as an ordinary file. Runtime state lives under ~/.claude/teams/, and Claude Code overwrites it, so don't edit it by hand. Define reusable roles as subagent files instead.

Subagents vs agent teams

Here's the short version of the comparison from Anthropic's docs:

The docs name four strong use cases for teams: parallel research and review, new modules where each teammate owns a piece, debugging with competing hypotheses, and changes that span frontend, backend, and tests. For sequential tasks, same-file edits, or work with many dependencies, a single session or subagents work better.

The debugging case is the most interesting. A single agent tends to find one plausible explanation and stop. Five teammates told to disprove each other's theories are less likely to anchor on the first idea. For running separate sessions yourself with no automated coordination, git worktrees are the lighter option. Our Claude Code best practices guide covers where each parallel approach fits.

Where Taku fits

Agent teams are a power-user feature: an experimental flag, a terminal, tmux if you want split panes, and enough Claude Code experience to write a good spawn prompt. A lot of people see a multi-agent setup shared online and never get it running.

If the setup step is where you keep stalling, Taku mirrors a working AI setup into a desktop workspace and runs it, so you can use a power user's configuration without reproducing their environment first. Taku is in Beta, and the Mac app is available now.

FAQ

What are Claude Code agent teams?

An experimental Claude Code feature where one session acts as a team lead and spawns teammates: separate Claude Code sessions, each with its own context window. They share a task list and message each other directly.

How do I turn on Claude Code agent teams?

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your shell or under env in settings.json. Then ask Claude, in plain language, to spawn teammates for a task.

Are agent teams the same as Claude Code teams of agents?

Yes. "Teams of agents" is the informal phrase; Anthropic's docs call the feature agent teams and describe it as orchestrating teams of Claude Code sessions.

Do agent teams cost more than subagents?

Yes. Each teammate is a separate Claude instance with its own context window, so token usage scales with the number of active teammates. Subagents return a summary to the caller, which keeps costs lower.

How many teammates should I use?

Anthropic suggests starting with 3 to 5 for most workflows, with roughly 5 or 6 tasks per teammate. Add more only when the work benefits from running simultaneously.

Can a teammate spawn its own team?

No. Nested teams aren't supported, a session has exactly one team, and only the lead manages it.

Do I need tmux for agent teams?

No. The default in-process mode works in any terminal. tmux, or iTerm2 with the it2 CLI, is only needed for split-pane mode.