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

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).

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:

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#

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

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

2. 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.
3. 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."
4. 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.
5. 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.

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).
• "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 and Claude's weekly limit 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 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 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.