What are agent teams in Claude Code and how do you turn them on?

Short answer

Agent teams let one Claude Code session act as team lead and start teammates: full, separate Claude Code sessions that share a task list and message each other directly. The feature is experimental and disabled by default; you turn it on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Each teammate has its own context window, so token use grows with the size of the team.

Agent teams vs subagents

Both split work over several Claude workers with their own context window. The difference is who talks to whom.

Subagents Agent teams
What runs A helper inside your session Separate, full Claude Code sessions
Communication Return a result to the caller; subagents that Claude named can also message each other Teammates message each other directly, and you can message any of them
Coordination The main agent manages all work A shared task list that teammates claim from, plus messages
Best for Focused tasks where only the result matters Work that needs discussion: review from several angles, competing hypotheses
Token cost Lower: a summary comes back Higher: every teammate is its own Claude instance
Status Standard feature Experimental, off by default

The docs advise checking whether a lighter option does the job before you set up a team. For most delegation, subagents are enough.

How to turn them on

  1. Set the environment variable in your shell or in settings.json:
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
  1. Start an interactive claude session. Teams do not form in -p runs or Agent SDK sessions.
  2. Ask for a team in plain language, for example: “Spawn three teammates to review PR #142: one on security, one on performance, one on test coverage.”
  3. Teammates appear in the agent panel below the prompt. Use the arrow keys to select one, Enter to read its transcript and message it, and Ctrl+T to toggle the task list.
  4. For a pane per teammate, run Claude Code inside tmux or iTerm2 with the it2 CLI, and set "teammateMode": "auto" in ~/.claude/settings.json. The default in-process mode works in any terminal.
  5. End a teammate by name (“Ask the researcher teammate to shut down”). The team’s shared directories are cleaned up when the session ends.

One side effect to know: with the variable on, Claude Code turns any subagent that Claude gives a name into a teammate, and Claude names subagents on its own. Teams can form when you did not ask for one.

How a team works

The session you start is the lead for its whole lifetime. It creates tasks, assigns them or lets teammates claim the next unblocked one, and combines the results. Tasks are pending, in progress or completed, and can depend on other tasks. Messages go through a mailbox per agent under ~/.claude/teams/.

Each teammate loads the same project context as a normal session, meaning CLAUDE.md, MCP servers and skills, plus the spawn prompt from the lead. It does not get the lead’s conversation history. Put the task details in the spawn prompt.

You can reuse a subagent definition from .claude/agents/ as a teammate role (“Spawn a teammate using the security-reviewer agent type”). Its tools and model apply; its skills field does not.

Three hooks help keep quality up: TeammateIdle, TaskCreated and TaskCompleted. Exit code 2 on these keeps a teammate working or blocks the task change, with feedback.

What it costs

The docs are direct: agent teams use significantly more tokens than a single session, and token use scales with the number of active teammates and how long each runs. The costs guide puts it at roughly 7x the tokens of a standard session when teammates run in plan mode. Its advice:

  1. Use Sonnet for teammates.
  2. Keep teams small, three to five to start.
  3. Keep spawn prompts focused, since everything in them sits in the teammate’s context from the start.
  4. Shut teammates down when they are done; an active teammate keeps using tokens.

On a subscription, that usage comes out of the same plan limits as your other Claude Code work. See Claude Code usage limits and what Claude Code costs per developer.

The misunderstanding: “more agents, faster work”

Past a point, extra teammates add coordination, not speed. The docs name the cases where teams lose: sequential tasks, edits to the same file, and work with many dependencies. Two teammates in one file overwrite each other. The tasks where teams do well are reading and arguing: parallel review, research, debugging with competing theories. That is also where the docs suggest starting.

Know the current limits before relying on a team for real work: in-process teammates do not survive /resume, task status can lag, there is one team per session, teammates cannot start their own teams, and the lead cannot be swapped.

What this means for a team of people

An agent team lives inside one developer’s session on one machine. The task list stays on disk afterwards, but the team, its messages and what the teammates figured out are scoped to that session. A colleague who starts their own team next morning starts from the repo and CLAUDE.md again, not from what yesterday’s team concluded.

Where Bombos fits

Agent teams share findings within one session. Bombos is a plugin that gives Claude Code and the team’s other AI tools one shared memory that outlives the session: team knowledge, rules learned from corrections, and what already sits in mail, documents and repos, traceable to its source. One developer can try it on their own agents first.

Related questions

Do agent teams work with claude -p or the Agent SDK?

No. Spawning teammates requires an interactive session. In non-interactive mode, a subagent that Claude names runs as an ordinary subagent even with agent teams enabled.

How many teammates should I use?

The docs suggest starting with three to five for most work. There is no hard limit, but token cost grows roughly in line with team size and coordination gets harder.

Can I resume a session with its team?

Not fully. /resume and /rewind do not restore in-process teammates. After resuming, tell the lead to spawn new teammates.

Why did Claude start teammates when I did not ask for a team?

While agent teams are enabled, a subagent that Claude names launches as a teammate, and Claude names subagents on its own. Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 0 to get plain subagents again.

Can teammates have their own permission mode?

Not at spawn time. A new teammate starts in the lead's mode, including bypassPermissions. You can switch a running teammate with Shift+Tab, and its permission prompts appear in the lead session.

Sources

  1. Claude Code docs: Orchestrate teams of Claude Code sessions
  2. Claude Code docs: Manage costs effectively
  3. Claude Code docs: Create custom subagents
The first half hour · free

What does your AI forget?

  1. 01You tell us which AI you use and where it keeps starting over.
  2. 02We show what a shared memory changes there, on your own examples.
  3. 03You keep the plan, with or without Bombos.
Piet Baudoin
Piet BaudoinYou talk to Piet, from the Bombos teamDutch team from Utrecht and Nijmegen · data in Europe
We reply the same working day.