# Claude Code agent teams: what they are and what they cost

> Claude Code agent teams run several Claude sessions with a lead, a task list and messages. How to turn them on, what they cost, and when not to.

Source: https://shuriken.sh/guides/claude-code-agent-teams

Claude Code agent teams run several Claude sessions with a lead, a task list and messages. How to turn them on, what they cost, and when not to.

By Shuriken Updated 27 October 2026 4 min read

**Contents**

Claude Code agent teams let one Claude Code session act as a lead that starts other Claude Code sessions as teammates. They share a task list, message each other, and each works in its own context window. The feature is experimental and off by default: set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 to turn it on. Expect it to spend tokens fast.

Below: what a team is, how to turn it on, what it costs on a subscription, and when plain subagents are the better tool.

## What are Claude Code agent teams? #

Anthropic's docs describe a team as four parts: a team lead (your main session, which "spawns teammates and coordinates work"), teammates ("separate Claude Code instances that each work on assigned tasks"), a shared task list, and a mailbox for messages between agents ([Claude Code docs: Agent teams](https://code.claude.com/docs/en/agent-teams)).

Three things make it different from anything else in Claude Code:

- Teammates talk to each other, not only to the lead. You can also message any teammate yourself.
- Teammates claim work from the shared task list. Tasks can depend on other tasks, and a blocked one can't be claimed until its dependencies are done.
- Each teammate is a full session. It loads your CLAUDE.md, MCP servers and skills like any session, but not the lead's conversation history: it starts from the spawn prompt.

## Agent teams vs subagents #

Both run work in parallel. The difference is who talks to whom, and what it costs. From Anthropic's comparison:

| | Subagents | Agent teams |
| --- | --- | --- |
| Context | Own context window; results return to the caller | Own context window; fully independent |
| Communication | Return a result to the caller | Teammates message each other directly |
| Coordination | The main agent manages all work | Messages plus a shared task list |
| Best for | Focused tasks where only the result matters | Complex work that needs discussion and collaboration |
| Token cost | Lower: results summarised back | Higher: each teammate is a separate Claude instance |

The docs' own advice is to "check whether a lighter option does the job" before setting up a team.

## How to turn agent teams on #

- Add the variable to ~/.claude/settings.json (or export it in your shell):

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

- Start an interactive claude session. Teams don't form in non-interactive mode: with -p, including Agent SDK sessions, a named helper runs as an ordinary subagent.
- Ask for a team in plain words, and say what each teammate does: "Spawn three teammates to review PR #142: one on security, one on performance, one on test coverage."
- Pick a teammate with the arrow keys in the agent panel and press Enter to read or message it. Ctrl+T shows the task list.
- When a teammate is done, ask the lead to shut it down. The team's folders are cleaned up when the session ends.

Teammates run inside your terminal by default. For a pane each, set teammateMode to "tmux" or "auto"; split panes need tmux or iTerm2, and the docs say they aren't supported in VS Code's terminal, Windows Terminal or Ghostty.

One side effect to know about: while teams are on, a subagent that Claude names on its own launches as a teammate, "so teams can form even when you didn't ask for one". Setting the variable back to 0 stops that.

Shuriken shows what every plan you hold has left in one figure, and what each turn costs as it runs.

[Download](https://shuriken.sh/download)

## Why agent teams burn through tokens #

Each teammate has its own context window, its own requests and its own copy of your project context. Anthropic is direct about the cost:

- "Agent teams use approximately 7x more tokens than standard sessions when teammates run in plan mode" ([Claude Code docs: Costs](https://code.claude.com/docs/en/costs)).
- "Token costs scale linearly": usage "is roughly proportional to team size".
- "Each active teammate continues consuming tokens until it exits or the session ends."

On a Claude subscription, all of that lands on one account's 5-hour window and weekly limit. A three-teammate review is roughly four sessions' worth of usage at once, before any of them writes code. Our guides on [why Claude Code burns tokens](https://shuriken.sh/guides/why-claude-code-burns-tokens) and [Claude's weekly limit](https://shuriken.sh/guides/claude-weekly-limit-explained) explain how that adds up over a week.

## When subagents are enough #

Most of the time. The docs say teams "work best when teammates can operate independently", and that "for sequential tasks, same-file edits, or work with many dependencies, a single session or subagents are more effective". A rough guide:

- Reach for subagents when you want research, a test run or a review done out of your main context and only the answer matters.
- Reach for a team when the workers need to argue with each other: competing theories for a bug, a review from three angles, or a feature split into parts that don't share files.
- Reach for separate sessions in git worktrees when you want parallel work you steer yourself, with no lead deciding for you. Our guide to [running Claude Code agents in parallel](https://shuriken.sh/guides/run-claude-code-agents-in-parallel) covers that route.

And know the limits before you rely on it. The docs list them: /resume and /rewind don't restore in-process teammates; task status can lag; one team per session; teammates can't start teams of their own; the lead can't be changed; and two teammates editing the same file overwrite each other.

## Seeing what runs #

Whatever you choose, the hard part is knowing what's running and spending. In the terminal, the agent panel lists teammates and subagents, and /usage breaks recent usage down by subagent.

If you run Claude Code chats in Shuriken, [Activity](https://shuriken.sh/features/activity) shows a chat's subagents, workflow phases and background commands in one live panel, with an "N running" pill, so a fan-out that's still going doesn't hide from you. Shuriken's Claude Code chats run through Anthropic's Agent SDK, and per the docs above a named helper there runs as an ordinary subagent, not a teammate. For a real team, use an interactive claude session.

Try the free tool: [Claude limit reset tracker](https://shuriken.sh/tools/limit-resets/claude)

Share

[X](https://x.com/intent/post?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-agent-teams&text=Claude%20Code%20agent%20teams%3A%20what%20they%20are%20and%20what%20they%20cost)[LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-agent-teams)[Hacker News](https://news.ycombinator.com/submitlink?u=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-agent-teams&t=Claude%20Code%20agent%20teams%3A%20what%20they%20are%20and%20what%20they%20cost)[Reddit](https://www.reddit.com/submit?url=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-agent-teams&title=Claude%20Code%20agent%20teams%3A%20what%20they%20are%20and%20what%20they%20cost)[E-mail](mailto:?subject=Claude%20Code%20agent%20teams%3A%20what%20they%20are%20and%20what%20they%20cost&body=https%3A%2F%2Fshuriken.sh%2Fguides%2Fclaude-code-agent-teams)

## Sources

- [Claude Code docs: Orchestrate teams of Claude Code sessions (agent teams)](https://code.claude.com/docs/en/agent-teams) (accessed 22 October 2026)
- [Claude Code docs: Manage costs effectively (agent team token costs)](https://code.claude.com/docs/en/costs) (accessed 22 October 2026)
- [Claude Code docs: Environment variables](https://code.claude.com/docs/en/env-vars) (accessed 22 October 2026)
- [Claude Code docs: Best practices](https://code.claude.com/docs/en/best-practices) (accessed 22 October 2026)

## Frequently asked questions

**How do I enable agent teams in Claude Code?**

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, in your shell or in the env block of settings.json. Then ask Claude for teammates in plain words. They are off by default.

**What is the difference between agent teams and subagents?**

Subagents work for the main session and report a result back. Teammates are separate Claude Code sessions that share a task list and message each other directly. Teams cost more tokens.

**How many tokens do agent teams use?**

Anthropic's docs say about 7 times more than a standard session when teammates run in plan mode, and that usage grows roughly in proportion to team size.

**Do agent teams work with claude -p?**

No. Anthropic's docs say spawning teammates needs an interactive session; in non-interactive mode, including Agent SDK sessions, Claude runs named helpers as ordinary subagents.

**How many teammates should I start with?**

Anthropic suggests 3 to 5 teammates for most work, and about 5 to 6 tasks per teammate. Three focused teammates often do better than five scattered ones.

Fuel

All your plans, in one fuel gauge.

Shuriken adds up what your subscriptions have left, one figure per provider and per limit, in the top bar.

[Download](https://shuriken.sh/download)

[Other platforms](https://shuriken.sh/download#main)

## Keep reading

- [Claude Pro vs Max for Claude Code: Guide 27 Oct 2026 5 min read Pro suits a few Claude Code sessions a week; Max suits daily heavy use and parallel agents. Prices, limits, the signs you've outgrown Pro, and upgrading.](https://shuriken.sh/guides/claude-pro-vs-max-for-claude-code)
- [Claude Code 1M context window: when it helps, what it costs: Guide 27 Oct 2026 4 min read Opus 4.7+, Sonnet 5+, Haiku 5.5 and Fable run with a 1M context in Claude Code by default. Why a huge session costs more every turn, and when /clear wins.](https://shuriken.sh/guides/claude-code-1m-context-window)
- [Claude Code: API key or subscription?: Guide 27 Oct 2026 6 min read Pro and Max are flat-priced with 5-hour and weekly limits; an API key bills every token with no plan limits. How to compare with your own numbers.](https://shuriken.sh/guides/claude-code-api-vs-subscription)
- [What Claude Code costs per developer, per month: Guide 27 Oct 2026 5 min read Claude Code cost per developer per month: Anthropic's average is $150 to $250 at API rates. How it compares with Pro, Max and Team seats, with the maths.](https://shuriken.sh/guides/claude-code-cost-per-developer)
- [Claude Code status line: show usage, model and cost: Guide 27 Oct 2026 6 min read The Claude Code status line runs your own script and shows its output at the bottom. It runs locally, uses no tokens, and /statusline writes one for you.](https://shuriken.sh/guides/claude-code-status-line)
- [Claude Max 5x vs 20x (2026): what you really get: Guide 27 Oct 2026 6 min read Claude Max 20x gives 20 times Pro's 5-hour allowance and Max 5x five. Anthropic publishes no weekly multiplier; users report 20x at 1.5 to 2 times 5x.](https://shuriken.sh/guides/claude-max-vs-max-20x)
- [Claude Team seats for Claude Code, explained: Guide 27 Oct 2026 5 min read Team Standard seats get 1.25x Pro's usage per session, Premium 6.25x, each with a 5-hour and weekly limit. Prices, Team vs Max, and a personal plan.](https://shuriken.sh/guides/claude-team-seats-for-claude-code)
- [Opus vs Sonnet for coding: which Claude model to use: Guide 27 Oct 2026 6 min read Opus vs Sonnet for coding: Sonnet 5.5 for well-scoped work, Opus 5.5 for long or open-ended jobs. Opus costs twice as much per token; judge it per task.](https://shuriken.sh/guides/opus-vs-sonnet-for-coding)

## Free tools

- [Claude limit reset tracker](https://shuriken.sh/tools/limit-resets/claude)
- [Codex limit reset tracker](https://shuriken.sh/tools/limit-resets/codex)