# Claude Code Agent Teams: How to Enable Them, vs Subagents, and What They Cost (Tested on Windows)

> Claude Code agent teams run several Claude sessions as a team: a lead plus named teammates that share a task list and message each other. How to turn them on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, how they differ from subagents, what a team cost next to subagents on the same task in my Windows test, and why teammates don't appear in claude -p.

By Tahir Nazir · Published 2026-11-19 · Updated 2026-11-19
Canonical: https://www.its-tahir.com/blog/claude-code-agent-teams

**Claude Code agent teams let one session, the lead, start several named teammates: each teammate is its own Claude Code session, and they share a task list and message each other. They're experimental and off by default. Turn them on with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`, start an interactive `claude` session, and ask for a team in plain words. In my Windows test a two-teammate team worked in the default in-process mode, cost about 1.7 times as much as two subagents (run in `claude -p`) on the same task, and never formed in `claude -p` itself.**

| You want to | Do this |
|---|---|
| Turn agent teams on | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your shell, or under `"env"` in settings.json |
| Start a team | In an interactive session: "Create an agent team with two teammates named …" |
| See and talk to teammates | Agent panel under the prompt: ↑/↓ to select, Enter to open, Esc to leave |
| Pick between teams and subagents | Workers need to talk to each other: team. Only the result matters: subagents |
| Run it on Windows | Default in-process mode works; split panes need tmux or iTerm2 |
| Teammates don't appear | Check you're not in `claude -p`, then ask explicitly for "an agent team" |
| Stop surprise teams | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0` in settings.json |

*Last reviewed 19 November 2026, against Anthropic's agent teams docs and the Claude Code changelog to 2.1.328. I ran the tests below on Claude Code 2.1.302 on Windows 11, in PowerShell inside VS Code's terminal, on a Max plan with Haiku 5.5, in a throwaway folder holding two two-line text files. Costs are Claude Code's own list-price estimates from one small run each, not a benchmark.*

![Claude Code agent teams vs subagents: subagents report one result back to the main agent and work in claude -p; an agent team has a lead and named teammates (@reader-a, @reader-b) that share a task list and message each other, interactive sessions only. Enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Same two-file task on Claude Code 2.1.302 with Haiku 5.5: subagents $0.028, agent team $0.048 with about 4x cached input. In-process mode works on Windows; split panes need tmux or iTerm2.](https://www.its-tahir.com/blog/claude-code-agent-teams/claude-code-agent-teams-vs-subagents.svg)

*Subagents report back; teammates talk to each other, and cost more for it.*

## What are agent teams in Claude Code?

**An agent team is a group of Claude Code sessions working together: a lead that you talk to, and teammates it starts and coordinates.** From Anthropic's [agent teams docs](https://code.claude.com/docs/en/agent-teams), what makes a team different from Claude simply delegating:

- **Every teammate is a full session** with its own context window, not a short-lived helper
- **They share a task list**, claim work from it and mark it done
- **They message each other directly**, not only through the lead
- **You can talk to any teammate** yourself, from the agent panel

Anthropic lists four places teams pay off: research and review, building separate modules in parallel, debugging with competing hypotheses, and changes that span frontend, backend and tests. For sequential work or several people editing the same file, the docs recommend a single session or subagents instead.

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

**Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to `1`, then use an interactive `claude` session.** Either export it in your shell:

```powershell
# PowerShell, this window only
$env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = "1"
claude
```

```bash
# macOS, Linux, WSL
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
claude
```

Or turn it on for every session in your [settings.json](https://tools.its-tahir.com/claude-code-settings):

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

**Once `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set to 1, two things change.** First, a team only forms in an interactive session: in `claude -p` and the Agent SDK, Claude uses ordinary subagents instead ([tested below](#why-does-claude-use-subagents-instead-of-an-agent-team)). Second, any subagent Claude gives a name now launches as a teammate, and Claude names subagents on its own, so teams can start when you didn't ask for one.

## How do I start an agent team?

**Describe the team in plain words: how many teammates, their names, and what each one does.** Anthropic's docs say Claude Code doesn't ask you to confirm the launch, and in my session it didn't. This is the prompt I used, in a folder holding `a.txt` and `b.txt`:

```text
Create an agent team with two teammates named reader-a and reader-b. reader-a reads a.txt
and reader-b reads b.txt. Each sends the first line of its file to the other teammate, then
reports both lines to you. Then shut the team down.
```

Claude Code printed `2 background agents launched (↓ to manage)` with `@reader-a` and `@reader-b` under it, and the agent panel below the prompt listed `main`, `reader-a teammate: read a.txt` and `reader-b teammate: read b.txt`. Messages between them showed as `Message from @reader-a (ctrl+o to expand)`, and each teammate reported back with a `Teammate @reader-a finished` row.

![Claude Code 2.1.302 on Windows with Haiku 5.5: 2 background agents launched (↓ to manage) @reader-a @reader-b, Teammate @reader-a finished, Message from @reader-a (ctrl+o to expand), Teammate @reader-b finished, auto mode on, and the agent panel listing main, reader-a teammate: read a.txt, reader-b teammate: read b.txt.](https://www.its-tahir.com/blog/claude-code-agent-teams/agent-team-running-windows.svg)

*My agent team run, recreated line for line from the screenshot: Claude Code 2.1.302 in VS Code's terminal on Windows 11.*

Both teammates read their file, sent the first line to the other, and the lead reported `alpha: the first file` and `beta: the second file`, which is right. Two things went less smoothly, and both are worth knowing:

- **The lead gave the teammates a `/tmp` path.** On Windows the files only resolved through the real Windows path of the folder, which both teammates noticed and worked around. If you name files for a team on Windows, use paths relative to the project.
- **Shutdown never confirmed.** The lead sent shutdown requests and reported: "The shutdown requests are still unconfirmed. Both teammates have gone idle, but I haven't received a shutdown response from either." Anthropic lists slow shutdown as a known limitation, and later versions fixed several shutdown bugs ([version table](#which-claude-code-versions-changed-agent-teams)), so update before relying on it.

From the agent panel: ↑ and ↓ select a teammate, Enter opens its transcript so you can message it directly, and Esc clears the selection or interrupts the teammate you're viewing. Ctrl+T toggles the task list.

## Agent teams vs subagents: what's the difference?

**In Claude Code, subagents work for the main agent and report one result back; teammates are full sessions that coordinate with each other.**

| | Subagents | Agent teams |
|---|---|---|
| What each worker is | A helper with its own context, returning a result to its caller | A full Claude Code session with its own context |
| Talking to each other | Only named subagents, and mainly through the main agent | Teammates message each other directly |
| Coordination | The main agent manages everything | A shared task list plus messages |
| Works in `claude -p` | Yes | No |
| Token cost | Lower | Higher: each teammate is a separate instance |
| Best for | Focused tasks where only the result matters | Work where the workers must share findings or challenge each other |

This comparison follows Anthropic's subagents vs agent teams table in the Claude Code docs. If two jobs don't need to talk, subagents are the cheaper and simpler choice, and they also work in scripts and CI.

## How much do Claude Code agent teams cost?

**More than subagents, and the gap grows with every teammate, because each teammate has its own context window. In one run on Claude Code 2.1.302 with Haiku 5.5 (19 November 2026), a two-teammate team cost $0.048 against $0.028 for two subagents.** I ran the same task both ways with Haiku 5.5 and read the cost Claude Code reports at list price:

| Same task: read two files, exchange first lines | Two subagents (`claude -p`) | Two-teammate agent team (interactive) |
|---|---|---|
| Cost at list price | $0.028 | $0.048 |
| Cached input read | about 304K tokens | about 1.3M tokens |
| Cache written | about 148K tokens | about 198K tokens |

That's about 1.7 times the cost and over four times the cached input for a task with almost no real work in it, most likely because each teammate is a full session that loads its own copy of Claude Code's tools and instructions. The two runs aren't a clean comparison: the subagents ran in `claude -p` because teams can't, and an interactive session loads more on its own. Read the ratio as a rough size, not a measurement. On a Claude subscription this is usage against your limits rather than a bill: my 5-hour bar read 6% before and after, so a tiny Haiku team barely registers. A team of Opus teammates on a real codebase is a different matter, and it's one way people end up at a 429 throttle: in the GitHub thread behind my [Claude Code error 429](/blog/claude-code-error-429) post, two Max subscribers say it starts when they run a team of subagents.

Two settings matter for cost. Per the [token usage section of Anthropic's docs](https://code.claude.com/docs/en/agent-teams#token-usage), an in-process teammate's prompt cache lasts five minutes by default even on a subscription, so set `subagentPromptCacheTtl` to `1h` if teammates sit idle between steps. And give teammates a cheaper model in your prompt (for example "use Sonnet for the teammates") when the work allows. For where the rest of the tokens go, see [why Claude Code uses so many tokens](/blog/why-claude-code-uses-so-many-tokens).

## Do Claude Code agent teams work on Windows?

**Yes. Claude Code agent teams work on Windows in the default in-process mode; I tested it on Claude Code 2.1.302 in PowerShell on Windows 11.** Teammates run inside your main terminal and appear in the agent panel, so any terminal works, including PowerShell and VS Code's terminal on Windows.

The other display mode, split panes, gives every teammate its own pane and needs tmux or iTerm2. Neither exists in plain PowerShell or cmd, so on Windows you stay in in-process mode unless you run Claude Code somewhere tmux works, such as WSL; I haven't tested split panes there. The `teammateMode` setting chooses the mode: `"in-process"`, `"tmux"`, `"iterm2"` or `"auto"`, where `auto` uses split panes only when Claude Code is already running inside tmux or iTerm2.

## Why does Claude use subagents instead of an agent team?

**Either the session can't run a team, or Claude decided the task didn't need one.** I hit the first case on purpose: with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` set, I asked `claude -p` for "an agent team with two teammates". The job finished, but Claude answered that agent teams weren't available in that session and used two subagents instead, exactly as Anthropic's docs say happens in non-interactive mode.

In an interactive session, if Claude still uses subagents, ask again and say "create an agent team" with the teammates named. The agent panel shows subagents and teammates in the same place, so look for the `teammate:` label on each row to be sure a team formed.

## Why aren't my Claude Code agent teammates working?

| Symptom | Cause and fix |
|---|---|
| Teammates never appear | You're in `claude -p`, the variable isn't set in that shell, or the task looked too small; set it, use an interactive session, and ask explicitly |
| A teammate row disappeared | It's hidden, not stopped: idle rows hide 30 seconds after the whole panel goes idle. Message the teammate by name to bring it back |
| Teams start when you didn't ask | A named subagent becomes a teammate while teams are on. Set the variable to `0` in settings.json; it's reread for every new subagent |
| Endless permission prompts | Teammates' prompts all land in the lead. Pre-approve common commands in your permission settings before starting the team |
| Teammates edit as freely as the lead | They start in the lead's permission mode, including auto and bypass; my session started in auto mode. See [Claude Code auto mode](/blog/claude-code-auto-mode) |
| A teammate stops early, or the lead declares victory too soon | Open the teammate, give it more instructions, or tell the lead to keep going |
| Shutdown never confirms | A known limitation; teammates finish their current step first. Update Claude Code, since 2.1.304 and 2.1.317 fixed shutdown bugs |
| After `/resume`, the lead messages teammates that are gone | In-process teammates aren't restored. Ask the lead to start new ones |
| Several in-process teammates fail with `Lock file is already being held` | Update: 2.1.328 made this far less frequent |

## What are the limits of agent teams?

**Claude Code agent teams have these documented limitations in Anthropic's docs (checked 19 November 2026):** one team per session, no nested teams (teammates can't start their own), the lead is fixed for the session, no per-teammate permission mode at spawn, no session resumption for in-process teammates, task status that can lag, and slow shutdown. In-process teammates also can't start background subagents. Teams don't put teammates in separate git worktrees, so split the work so no two teammates edit the same file.

Anthropic suggests three to five teammates for most work, with tasks sized so each teammate has a clear, self-contained piece. If you want a guard that refuses risky tool calls whichever teammate makes them, a [Claude Code mod](/blog/claude-code-mods) can do that from inside Claude Code.

## Which Claude Code versions changed agent teams?

| Version | Change |
|---|---|
| 2.1.328 | Starting several in-process teammates at once: far fewer fail with `Lock file is already being held` |
| 2.1.327 | In-process teammates on a different model from the lead now compact at their own context limit, on their own model |
| 2.1.326 | Code Mode can be turned on while agent teams are enabled |
| 2.1.325 | An unknown `teammateMode` value is now reported instead of silently ignored; tmux and iTerm2 teammates start in the session's folder |
| 2.1.323 | Split-pane teammates check that requests come from their lead |
| 2.1.317 | Fixed tmux and iTerm2 teammates starting in auto mode when the lead was in manual mode; fixed a re-created teammate being removed by an earlier shutdown approval |
| 2.1.311 | Fixed an empty task list after `--resume`, `--continue` or `/resume` |
| 2.1.309 | Split-pane teammates inherit the lead's `--disallowedTools` and `--tools` rules |
| 2.1.304 | Approving a shutdown request from the main session no longer exits the whole CLI |
| 2.1.295 | Fixed in-process teammates failing their first `SendMessage` until they loaded the tool |

From the [changelog](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md). I tested on 2.1.302, before the 2.1.304 and 2.1.317 shutdown fixes, which may explain the shutdown that never confirmed.

**Key takeaways**

- Claude Code agent teams are a lead plus named teammates, each a full session, sharing a task list and messaging each other. They're experimental and off by default.
- Enable them with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and an interactive session; in claude -p Claude uses subagents instead, which I confirmed.
- Use subagents when only the result matters; use a team when workers need to share findings or challenge each other.
- In my Windows test a two-teammate team cost $0.048 against $0.028 for two subagents on the same task, with about 4x the cached input.
- In-process mode works on Windows; split panes need tmux or iTerm2. Use project-relative paths: my lead handed teammates a /tmp path.
- While teams are on, any named subagent becomes a teammate. Set the variable to 0 in settings.json to stop surprise teams.

## FAQ

## Related

- [Claude Code not working? 30+ errors and how to fix them](/blog/claude-code-troubleshooting)
- [Claude Code error 429](/blog/claude-code-error-429)
- [Why Claude Code uses so many tokens](/blog/why-claude-code-uses-so-many-tokens)
- [Claude Code mods](/blog/claude-code-mods)
- [Claude Code auto mode](/blog/claude-code-auto-mode)
- [Claude limit reset](/blog/claude-limit-reset)

## FAQ

### What are agent teams in Claude Code?

Agent teams are an experimental Claude Code feature where one session, the lead, starts several named teammates. Each teammate is its own Claude Code session with its own context window; they share a task list and can message each other directly, while the lead assigns work and collects the results. They are off by default.

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

Set the environment variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, either in your shell or under "env" in settings.json, then start an interactive claude session and ask for a team in plain words, for example 'Create an agent team with two teammates named reader-a and reader-b'. Anthropic's docs say teams don't form in claude -p or Agent SDK sessions, and my claude -p test used subagents instead.

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

Subagents are workers the main agent starts; each does its task and returns one result to the main agent rather than to each other. Agent teammates are full Claude Code sessions that share a task list and message each other, coordinated by a lead. Teams suit work where the workers need to compare notes; subagents are cheaper for focused tasks where only the result matters.

### Do Claude Code agent teams cost more?

Yes. Each teammate is a separate Claude instance with its own context, so usage grows with the number of teammates. In my test on Claude Code 2.1.302 with Haiku 5.5, the same two-file task cost $0.028 at list price with two subagents and $0.048 with a two-teammate agent team, with about four times the cached input. On a Claude plan that is usage against your limits, not a bill.

### Do Claude Code agent teams work on Windows?

Yes, in the default in-process mode: teammates appear in the agent panel under the prompt, and you switch between them with the arrow keys. I ran a two-teammate team in PowerShell in VS Code's terminal on Windows 11. Split-pane mode needs tmux or iTerm2, so it isn't available from plain PowerShell or cmd.

### Why does Claude use subagents instead of creating an agent team?

Either the session can't run teams or Claude chose not to. Teams only form in interactive sessions with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1; in claude -p, Anthropic's docs say Claude uses subagents instead, which my test confirmed. In an interactive session, ask again and explicitly say 'create an agent team' and name the teammates.

### Why do agent teams start when I didn't ask for one?

While agent teams are enabled, any subagent Claude gives a name launches as a teammate, and Claude names subagents on its own so it can message them later. To get ordinary subagents back, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 0 in settings.json; Claude Code rereads it each time it spawns a subagent.

### How many teammates should an agent team have?

Anthropic's docs suggest starting with three to five teammates for most work. There is no hard limit, but token use grows with every teammate and coordination gets harder, and the docs note that three focused teammates often outperform five scattered ones.

## Sources

- [Orchestrate teams of Claude Code sessions (Claude Code docs)](https://code.claude.com/docs/en/agent-teams)
- [Run agents in parallel: subagents, agent view, agent teams, dynamic workflows (Claude Code docs)](https://code.claude.com/docs/en/agents)
- [Subagents (Claude Code docs)](https://code.claude.com/docs/en/sub-agents)
- [Agent team token costs (Claude Code docs)](https://code.claude.com/docs/en/costs)
- [Claude Code changelog: agent team and teammate fixes, 2.1.260 to 2.1.328](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md)
