Claude Code agent teams: setup and limits

What are Claude Code agent teams, and are they stable?

Agent teams coordinate several Claude Code instances. Per the official agent teams page, one session acts as the team lead: it coordinates work, assigns tasks and synthesizes results. Teammates work independently, each in its own context window, and talk directly to each other. You can also message any teammate yourself without going through the lead.

Before you set up a team, the docs suggest checking whether a lighter option does the job. Subagents work inside a single session, and cross-session messaging lets Claude pass findings between sessions you run yourself. A team is the heavier tool: more tokens, more coordination, and more to go wrong.

How are agent teams different from subagents?

Both parallelize work. The difference is who talks to whom. A subagent reports back to the main agent and ends. Teammates share a task list, claim work and message each other.

The docs' summary: use subagents for quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other and coordinate on their own. For sequential tasks, same-file edits or work with many dependencies, a single session or subagents are more effective.

How do you enable agent teams?

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

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

Two side effects are worth knowing before you turn it on.

• Ordinary delegation changes. With teams enabled, a subagent that Claude gives a name launches as a teammate. Claude can name subagents on its own, so a team can form even when you never asked for one. Claude Code does not ask you to confirm the launch.
• Interactive sessions only. In non-interactive mode with the -p flag, including Agent SDK sessions, Claude does not spawn teammates. A named subagent runs as an ordinary subagent there.

To undo the first side effect, set the same variable to 0. The docs say you do not need a new session: Claude Code reapplies settings-file env values to the running session when you save the file. A 1 set in project settings, local settings, a --settings payload or managed settings can still override your user-level 0, because those sources apply later.

How do you start your first agent team?

After enabling the feature, describe the task and the teammates you want in natural language. Claude spawns them and coordinates based on your prompt. The docs' first example works because the three roles are independent:

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 then fills a shared task list, spawns a teammate per perspective, lets them explore, and synthesizes the findings. One catch from the docs: Claude may sometimes use subagents instead of creating a team, and subagents appear in the same agent panel as teammates, so the panel alone does not prove a team formed. If you got subagents, ask again and explicitly request an agent team.

In the lead's terminal, teammates are listed in the agent panel below the prompt input:

• Up and down arrows select a teammate.
• Enter opens the selected teammate's transcript so you can message it directly.
• Escape clears the selection. While you are viewing a teammate's transcript, Escape interrupts that teammate's current turn.
• `x` on a selected teammate stops it, and Ctrl+T toggles the task list (both in in-process mode).

Idle teammates are not gone when their row disappears. Once every agent in the panel is idle, idle rows hide after 30 seconds and reappear on the teammate's next turn; the teammate stays running and addressable.

What display modes do agent teams support?

Set the mode with the teammateMode setting in ~/.claude/settings.json. The documented values are "in-process" (default), "auto", "tmux" and "iterm2". "auto" uses split panes when you are already inside a tmux session or in iTerm2 with it2 installed, and falls back to in-process otherwise. "tmux" enables split panes and detects tmux or iTerm2 from your terminal. "iterm2" uses iTerm2's native panes and shows an error with the install command if it2 is missing.

# ~/.claude/settings.json
{
  "teammateMode": "auto"
}

# or for one session only (experimental flag, not shown in claude --help)
claude --teammate-mode auto

For iTerm2, enable the Python API under iTerm2, Settings, General, Magic. The docs note that tmux has known limitations on some operating systems and works best on macOS, and that split-pane mode is not supported in VS Code's integrated terminal, Windows Terminal or Ghostty.

How do you steer a running team?

Tell the lead what you want. It handles coordination, task assignment and delegation.

• Pick the number and models. Claude decides the team size from your task, or you can name it: "Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for each teammate." The docs list how a teammate's model is chosen: the model named in your spawn prompt first, then the subagent definition's model, then CLAUDE_CODE_SUBAGENT_MODEL, then the lead's model.
• Name your teammates. The lead assigns every teammate a name when it spawns them, and teammates message each other by name. For predictable names, say what to call each one in the spawn instruction.
• Have teammates plan first. A teammate spawned while the lead is in plan mode works read-only until its plan is ready. Per the docs, if you have not changed that teammate's permission mode, Claude Code approves its plan as soon as the request arrives without the lead reviewing it.
• Reuse subagent definitions. Say "Spawn a teammate using the security-reviewer agent type to audit the auth module" and Claude Code applies that definition's tools, model and body to the teammate. It does not apply the definition's skills.
• Assign or let them claim. Tasks have three states: pending, in progress and completed, and can depend on other tasks. The lead can assign explicitly, or teammates self-claim the next unassigned, unblocked task. Claiming uses file locking to prevent two teammates taking the same task.
• Shut one down. Ask the lead, for example "Ask the researcher teammate to shut down". The teammate can approve or reject with an explanation.

Permissions follow the lead. Teammates start with the lead's permission mode (except dontAsk, which they do not inherit), and their permission prompts appear in the lead session. Pre-approve common operations in your permission settings before spawning, or you will spend the session approving prompts.

For quality gates, three hooks apply to teams: TeammateIdle, TaskCreated and TaskCompleted. Each blocks its action when your script exits with code 2 and sends your feedback back.

What are good tasks for an agent team?

The docs name four strong use cases: research and review, new modules or features that teammates can each own, debugging with competing hypotheses, and cross-layer changes where each teammate owns frontend, backend or tests. They recommend starting with tasks that have clear boundaries and do not require writing code, such as reviewing a PR, researching a library or investigating a bug.

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

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

The debate structure is the point. The docs explain that sequential investigation suffers from anchoring: once one theory is explored, later investigation is biased toward it. Several investigators trying to disprove each other make the surviving theory more likely to be the real cause.

A teammate does not see your conversation, only the project context (CLAUDE.md, MCP servers, skills) plus the spawn prompt. So put the specifics in the prompt: which directory, what to focus on, what the stack is, what format to report in. If you are looking for something to point a team at, browse AI agent ideas on the board and ask a team to review the build prompt of one.

How many teammates should you use, and what does it cost?

There is no hard limit on teammates, but the docs give practical guidance: start with 3 to 5 for most workflows. Token costs scale linearly because each teammate has its own context window, coordination overhead grows with headcount, and returns diminish. The docs' example: with 15 independent tasks, three teammates is a good start, and three focused teammates often outperform five scattered ones.

Agent teams use significantly more tokens than a single session, per the docs. For routine tasks a single session is more cost-effective. Also keep file ownership separate: two teammates editing the same file leads to overwrites, so give each a different set of files.

Where does Claude Code store a team?

The team name is session- followed by the first eight characters of the session ID. The team config holds runtime state such as session IDs and tmux pane IDs, so do not edit it by hand: changes are overwritten on the next state update. There is no project-level team config; a file like .claude/teams/teams.json is not recognized. To define reusable roles, use subagent definitions instead.

What are the known limitations and fixes?

• No session resumption with in-process teammates. /resume and /rewind do not restore them. After resuming, tell the lead to spawn new teammates.
• Task status can lag. Teammates sometimes fail to mark tasks complete, which blocks dependent tasks. Check whether the work is done and update the status or nudge the teammate.
• One team per session, no nested teams. Teammates cannot spawn their own teammates. The lead is fixed for the session's lifetime.
• Shutdown can be slow. Teammates finish their current request or tool call first.
• Teammates stop early. Select the teammate and press Enter to read its output, then give instructions or spawn a replacement. The lead can also declare the team finished too soon; tell it to keep going.
• The lead starts doing the work itself. Tell it: "Wait for your teammates to complete their tasks before proceeding."
• Orphaned tmux sessions. Run tmux ls, then tmux kill-session -t <session-name> for the one the team created.

For a hands-off alternative that does not need the experimental flag, the docs point to git worktrees, which let you run several sessions yourself without automated team coordination.