# Claude Code agent teams: how to set them up and when to use them

> Claude Code agent teams, step by step: turn them on, start a team, give each teammate a pane, and when subagents or a team across vendors fit better.

Published 2026-11-16 on the Starkomand blog: https://starkomand.com/blog/claude-code-agent-teams/

Claude Code agent teams let one Claude Code session lead several others. The lead splits the work into tasks, the teammates pick them up, and they message each other directly instead of reporting only to the lead. The feature is experimental and off until you set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`.

The facts below come from Anthropic's [agent teams](https://code.claude.com/docs/en/agent-teams) docs, read on 16 November 2026. I did not run a team for this post, so there are no screenshots and no timings. I build Starkomand, a Mac app for running coding agents on one canvas, and the last section covers its own team feature, which can mix Claude Code with Codex and other CLIs.

## What are Claude Code agent teams?

A team is one lead session plus teammates. Each teammate is a full Claude Code session with its own context window. The lead creates tasks on a shared task list, teammates claim them, and anyone on the team can message anyone else. You can also talk to a teammate yourself without going through the lead.

That is the difference from subagents. A subagent does one job inside your session and returns a result to the caller. A teammate keeps working, claims the next task when it finishes one, and can argue with the other teammates about what they found.

## How do I turn on agent teams?

Add the variable to `~/.claude/settings.json`, or export it in your shell:

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

Two things change once it is on. Teams need an interactive session, so `claude -p` and Agent SDK runs never spawn teammates. And Claude may form a team you did not ask for: while teams are enabled, a subagent that Claude names launches as a teammate.

## How do I start a team?

Describe the task and the teammates in plain words. Anthropic's own example:

```text
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.
```

The teammates appear in an agent panel under the prompt. Use the up and down arrows to select one, **Enter** to open its transcript and message it, and **Escape** to clear the selection. **Ctrl+T** shows the task list, and **x** stops the selected teammate. Claude sometimes uses subagents instead, and they appear in the same panel, so ask again for an agent team if that happens.

## Can each teammate get its own pane?

Yes, in tmux or iTerm2. By default teammates run inside your main terminal. Set `teammateMode` to `"auto"` in `~/.claude/settings.json`, start `claude` inside tmux or iTerm2, and each teammate opens in its own split pane:

```json
{
  "teammateMode": "auto"
}
```

iTerm2 also needs the [`it2` CLI](https://github.com/mkusaka/it2) and its Python API turned on under **Settings → General → Magic**. Outside both, set `teammateMode` to `"tmux"`, and the panes open in a separate tmux session that you attach to from a second terminal. For one session only, run `claude --teammate-mode auto`. The flag is experimental and does not appear in `claude --help`.

The [tmux setup post](https://starkomand.com/blog/claude-code-tmux/) has the rest of the tmux config Claude Code wants, and the [terminal comparison](https://starkomand.com/blog/best-terminal-for-claude-code/) says which terminals show split panes without tmux.

## Which model does each teammate use?

The first of these that applies:

1. The model your prompt names for that teammate, as in "Use Sonnet for each teammate".
2. The `model` of the subagent definition the teammate was spawned from.
3. `CLAUDE_CODE_SUBAGENT_MODEL`, when it is set to anything but `inherit`.
4. The lead's current model.

Naming a cheaper model in the prompt is the simplest way to keep a large team affordable.

## Agent teams vs subagents: which should I use?

| | Subagents | Agent teams |
|---|---|---|
| Context | Their own; results return to the caller | Their own; fully independent |
| Communication | Report back to the caller | Message each other directly |
| Coordination | The main agent manages the work | A shared task list, plus messages |
| Token cost | Lower | Higher: every teammate is a separate session |

Anthropic's advice is to use subagents when only the result matters and teams when the workers need to share findings and challenge each other. The docs name four places where teams earn their cost: research and review, new modules that split cleanly, debugging with competing hypotheses, and changes that span frontend, backend and tests.

## How many teammates should I start with?

Three to five. Token use grows with every active teammate, coordination gets harder, and past a point more teammates stop making the work faster. The docs suggest five or six tasks per teammate, so the lead can move work from one that gets stuck.

Two habits prevent most trouble. Give each teammate its own files, because two teammates editing the same file overwrite each other. And if you are new to teams, start with work that reads rather than writes: reviewing a PR, researching a library or chasing a bug.

## What are the limits?

The feature is experimental, and Anthropic lists these limits:

- `/resume` and `/rewind` do not bring back in-process teammates.
- A teammate sometimes forgets to mark a task done, which blocks the tasks that depend on it.
- One team per session, and teammates cannot start teams of their own.
- The lead stays the lead; you cannot hand leadership to a teammate.
- Shutdown waits for each teammate to finish its current request.

## Can a team mix Claude Code and Codex?

Not with Anthropic's agent teams: every teammate is a Claude Code session. A team across vendors needs something outside Claude Code, and that is part of what Starkomand does.

In Starkomand, an agent on the canvas can start workers of its own while it keeps working. Ask the agent in a window, for example "split this: a Codex worker writes the tests and a Claude worker reviews the diff". Each worker opens as its own terminal window, wired to the agent that started it, and runs the CLI its role is set to under **Settings → Workflows**, on the model saved there or the one Auto routing picks. The lead can wait for its workers, read what each one reported and send it more instructions. One agent can have up to six unfinished workers at a time.

Starkomand's team is not Anthropic's feature. It works with Claude Code, Codex, Cursor and the other CLIs the app launches, each signed in with your own plan. It has no shared task list. Instead, each worker gets one written job and reports back when it finishes. If you only use Claude Code and like the task list, Anthropic's teams in tmux are the simpler setup.

## The Starkomand features in this post

- **Workers**: ask an agent to split the work, and each worker opens as a window wired to it.
- **Roles**: **Settings → Workflows** sets which CLI each kind of worker runs.
- **Matchups**: [Codex vs Claude Code](https://starkomand.com/compare/codex-vs-claude-code/) and [Cursor vs Claude Code](https://starkomand.com/compare/cursor-vs-claude-code/) compare the CLIs you might put on one team.
