Claude Code Agent Teams: Setup, Cost and When to Use

Claude Code agent teams let one session act as a lead that spawns several teammates. Each teammate is a full Claude Code session with its own context window, and they share a task list and message each other. The feature is experimental and off by default. Turn it on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, and use it only when parallel workers need to talk to each other. Otherwise subagents or a single session are cheaper and simpler.

This guide covers setup, how to steer a team, how to gate its work with hooks, what it costs and where it breaks. Everything here comes from Anthropic's Claude Code documentation as read on 5 November 2026. The feature is experimental, so check the docs before relying on details.

What are Claude Code agent teams?

A team has four parts:

Teammates load the same project context as any session (CLAUDE.md, MCP servers, skills) plus the spawn prompt from the lead. The lead's conversation history does not carry over. That one fact drives most of the advice below: whatever a teammate needs to know has to be in its spawn prompt or in your project files.

Task claiming uses file locking so two teammates cannot grab the same task. Tasks are pending, in progress or completed, and can depend on each other. A blocked task is not self-claimed by teammates, though you or the lead can still assign it.

How do I enable agent teams?

Set the environment variable in your shell or in settings.json:

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

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

• While teams are enabled, a subagent that Claude names launches as a teammate. Claude names subagents on its own so it can message them later, so a team can form without you asking, and Claude Code does not ask you to confirm the launch.
• Spawning teammates needs an interactive session. With -p (non-interactive mode, including Agent SDK sessions) Claude does not spawn teammates, and a named subagent runs as an ordinary subagent. So teams are not an option for headless CI runs.

To switch the behaviour off again, set the variable to 0. Claude Code re-reads settings-file env values when you save, so you do not need a new session. Project, local, --settings and managed settings can still override a user-level 0.

How do I start a team?

You describe the roles in plain language. The docs' own starter 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.

Claude may use subagents instead. Subagents and teammates share the same agent panel, so the panel does not prove a team formed. If you got subagents, ask again and explicitly request an agent team. To get predictable names for later prompts, say what to call each teammate when you spawn it.

In the lead's terminal, the agent panel lists teammates. Arrow keys select one, Enter opens its transcript so you can message it directly, and Escape clears the selection (or interrupts that teammate's turn while you are viewing it). In in-process mode, x stops a selected teammate and Ctrl+T toggles the task list.

Display modes

The default is in-process: every teammate runs inside your terminal, and it works in any terminal. Split panes give each teammate its own pane and need tmux, or iTerm2 with the it2 CLI. Set the mode in ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

"auto" uses split panes when you are already inside tmux (or in iTerm2 with it2) and falls back to in-process otherwise. "tmux" turns on split panes and detects whether to use tmux or iTerm2, and "iterm2" uses iTerm2 panes explicitly. A per-session flag exists, claude --teammate-mode auto, but it is experimental and absent from claude --help. Split panes are not supported in VS Code's integrated terminal, Windows Terminal or Ghostty.

Which model does each teammate use?

Claude Code takes the first of these that applies:

1. The model your spawn prompt names for that teammate.
2. The model in the subagent definition it was spawned from (inherit means the lead's model).
3. CLAUDE_CODE_SUBAGENT_MODEL, if set to anything but inherit.
4. The lead's current model.

(Before v2.1.251 the environment variable came first, and an installed mod or CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 can change the order. See the docs if you use either.)

So the simple way to control cost is to say it in the prompt:

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

A teammate's model and fast mode are fixed at spawn. /model and /fast typed while you view a teammate change the lead, not the teammate; Claude Code does not run them from that view.

Reuse subagent definitions as teammate roles

You can define a role once, such as a security-reviewer, and use it both as a subagent and as a teammate:

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

The definition's tools list and model apply, and its body is added to the teammate's instructions. Its skills do not apply: teammates load skills from your project and user settings. There is no project-level team config file. A .claude/teams/teams.json is treated as an ordinary file, and the generated team config under ~/.claude/teams/ should not be edited by hand, so reusable roles belong in subagent definitions.

When should I use a team instead of subagents?

Subagents report back to the caller and are cheaper because results are summarised into the main context. Teams cost more because every teammate is a separate instance, but teammates can challenge each other. Anthropic's examples of good fits:

• Parallel review with distinct lenses: one teammate on security, one on performance, one on test coverage for the same PR, with the lead synthesising.
• Competing hypotheses for a bug: several teammates each try to disprove the others' theories. The docs argue this fights anchoring, where a single investigator stops at the first plausible cause.
• New modules or cross-layer work: each teammate owns a separate set of files.

Poor fits are sequential tasks, same-file edits and work with many dependencies. If you are new to this, start with research or review tasks that write no code.

How do I keep teammates from conflicting?

Two teammates editing one file leads to overwrites, so split the task by files. Pre-approve common operations in your permission settings before spawning, because teammate permission prompts appear in the lead session. Know these permission rules:

• A new teammate starts in the lead's permission mode, including bypassPermissions. You cannot set per-teammate modes at spawn.
• If the lead is in dontAsk, teammates start in Manual mode.
• For split-pane teammates, --allowedTools is not passed along. Put rules under permissions.allow via --settings instead, for example claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}'.
• A teammate cannot approve a prompt on your behalf, and cannot relay a denied action to another teammate.

Plan before implementing

If the lead is in plan mode when it spawns a teammate, that teammate works in plan mode until its plan is ready. Be careful: if you have not changed that teammate's permission mode since it was spawned, Claude Code approves the plan as soon as the request arrives, without the lead reviewing it. The lead reviews a plan only if you press Shift+Tab on a running in-process teammate to put it in plan mode yourself. Then the lead approves it or sends it back.

How do I enforce quality gates with hooks?

Three hook events apply to teams. Exit with code 2 to push back:

• TeammateIdle: runs when a teammate is about to go idle; exit 2 sends feedback and keeps it working.
• TaskCreated: exit 2 prevents the task being created and sends feedback.
• TaskCompleted: exit 2 prevents completion and sends feedback.

A TaskCompleted hook that runs your tests and refuses completion on failure is a sensible first one.

How much do agent teams cost?

Each teammate has its own context window and keeps consuming tokens until it exits or the session ends. Anthropic's cost page says agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode. It recommends:

• Use Sonnet for teammates.
• Keep teams small, since usage is roughly proportional to team size. The agent teams page suggests starting with 3-5 teammates and notes that three focused teammates often outperform five scattered ones.
• Keep spawn prompts focused, since everything in them is in context from the start.
• Shut teammates down when done, for example "Ask the researcher teammate to shut down".
• Size tasks as self-contained units (a function, a test file, a review). The docs suggest 5-6 tasks per teammate.

One cache detail: an in-process teammate's requests sit outside the main conversation's cache bucket, so its cache holds for five minutes by default, even on a subscription. Setting subagentPromptCacheTtl to 1h extends that, but the API bills one-hour cache writes at a higher rate. On plans with usage limits, several teammates also use the limit up faster, and /usage shows what share of recent usage goes to skills, subagents, plugins and MCP servers.

What are the limits of agent teams?

From the documentation:

• /resume and /rewind do not restore in-process teammates. After a resume, tell the lead to spawn new ones.
• Task status can lag: teammates sometimes fail to mark tasks complete, which blocks dependent tasks.
• Shutdown can be slow, since teammates finish their current request or tool call first.
• One team per session, no nested teams, and the lead is fixed for the session's life.
• An in-process teammate's own subagents run in the foreground.
• The lead may start implementing tasks itself, or decide the team is finished early. Tell it to wait for teammates, or to keep going.
• An orphaned tmux session may remain. Use tmux ls and tmux kill-session -t <session-name>.

Treat a team as a short, supervised run. The docs warn that letting one run unattended for too long increases the risk of wasted effort.

How Atlas relates to this

Atlas is a team of AI engineers built on Claude Code. Each engineer is its own Claude Code session with a written role and its own working folder, so engineers do not edit the same files. Work is shared through a board where claims hold a lease, and every build is reviewed as it finishes. Atlas runs on your own Claude Pro or Max plan, with an optional daily budget that warns at 50% and 80% and pauses at 100%.

What Atlas does not do today is the debate pattern above, where several investigators each try to disprove the others' theories about one bug. That is coming to Atlas, built in, so it needs no setup. Until then, you can run it yourself with the prompt shown in the docs and the steps in this guide. You can see how the rest works on the Atlas home page.

Conclusion

Start small: enable the variable, ask for three Sonnet teammates on a review or a bug with several plausible causes, give each its own files and a focused prompt, and add a TaskCompleted hook. Shut teammates down when they finish. If the work is sequential or lives in a few files, a single session or subagents will do it for less.