Agent teams

Coordinating several Claude Code sessions as one team — the experimental flag, spawning teammates, the agent panel, display modes, the shared task list, permissions, limits, and cost.

An agent team is several Claude Code sessions working together. Your session becomes the lead: it spawns teammates, hands out tasks, and synthesizes the results. Each teammate is a full, independent Claude Code instance with its own context window.

The part that makes it a team rather than a fan-out: teammates message each other directly and share one task list, and you can open any teammate and talk to it without going through the lead.

Turning it on

Set the variable in your shell environment, or in settings.json:

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

That’s the whole setup. Since v2.1.178 there is no create-a-team step — the team forms when the first teammate is spawned, and its directories are cleaned up when the session exits. The old TeamCreate and TeamDelete tools no longer exist.

Versus subagents

Both parallelize work. Choose on whether the workers need to talk to each other:

	Subagents	Agent teams
Context	Own context window; the result returns to the caller	Own context window; fully independent
Communication	Report back to the main agent only	Teammates message each other directly
Coordination	The main agent manages all work	Shared task list, self-coordinated
Best for	Focused tasks where only the result matters	Work that needs discussion and collaboration
Token cost	Lower — the result is summarized back	Higher — every teammate is a separate Claude instance

The strongest cases are parallel research and review, new modules where each teammate owns different files, debugging with competing hypotheses, and cross-layer changes spanning frontend, backend, and tests.

Teams add coordination overhead. For sequential work, same-file edits, or heavily dependent steps, a single session or plain subagents win. When the plan itself should live in code rather than in a lead’s context, reach for a dynamic workflow instead.

Starting one

Describe the task and the teammates you want, in your own words. Claude spawns them, populates the shared task list, and synthesizes findings at the end.

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.

Claude may also propose a team on its own when a task looks parallel — you confirm first. It never spawns teammates without approval.

Writing the spawn prompt

A teammate wakes up with your project and no memory of your conversation, so the spawn prompt is the entire briefing. A shape that holds up:

The goal

What’s being built and what “done” looks like. Without it a teammate knows its own task but not why it has neighbours — and it can’t tell when a message from one of them matters.

The team

How many teammates, and which model they run.

Each teammate

Its role, the files or directory it owns, what it produces, and who it messages when it’s done.

The final deliverables

What you want back once the lead has synthesized everything.

Goal: build a working full-stack app with a REST API and a React frontend.
The end result should run on http://localhost:3000 with users and posts,
plus a QA report confirming it works.

Spawn 3 teammates using Sonnet:

1. Backend dev — build the REST API in src/api/. Create routes for users
   and posts. When done, message the frontend dev with the endpoints.
2. Frontend dev — build the React UI in src/components/. Wait for the
   backend dev's message with the API contract, then wire up the fetches.
3. QA — write tests in tests/. Start with unit scaffolding, then add
   integration tests once backend and frontend report done.

Final deliverables:
- a running app on http://localhost:3000
- tests/report.md with pass/fail results
- docs/build-summary.md — what was built, key decisions, how to run it

Both dependency edges are spelled out. “Message the frontend dev” and “wait for the backend dev’s message” are instructions — the team doesn’t infer the handoff graph from the order you listed the roles in.

Do	Don’t
Give each teammate its own files	Let two teammates edit one file
Say what the output is and where it goes	Ask for “a review” or “some improvements”
Name the recipient of every handoff	Assume they’ll work out who to talk to
3–5 teammates	Spawn a swarm of ten
Restate the context they need	Assume your conversation carried over

The agent panel

Teammates are listed below the prompt input in the lead’s terminal.

Key	Action
`↑` / `↓`	Select a teammate
`Enter`	Open its transcript and message it directly
`Esc`	Interrupt the selected teammate’s current turn
`x`	Stop the selected teammate
`Ctrl+T`	Toggle the task list

Rows that vanish aren't dead teammates

Since v2.1.199 an idle row stays visible while any other agent is still working. Once the whole panel goes idle, idle rows hide after 30 seconds and come back on the teammate’s next turn — it keeps running and stays addressable by name the whole time.

More than three idle teammates

The surplus rows collapse into one counter row, such as 2 idle agents when five are idle. Enter expands it, Esc collapses it again. Working teammates, failed teammates, and the one you’re viewing always keep their own row.

Display modes

Mode	What you get
In-process	Everyone runs in your main terminal; you switch with the agent panel. Works anywhere, no setup.
Split panes	One pane per teammate, all output visible at once, click into a pane to interact. Needs tmux or iTerm2.

The default is "in-process" (before v2.1.179 it was "auto", so upgraded sessions that used to open split panes now stay in one terminal). Set teammateMode in ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

Value	Behaviour
`in-process`	Everything in one terminal — the default
`auto`	Split panes when you’re already inside tmux, or in iTerm2 with `it2` installed; otherwise in-process
`tmux`	Split panes, auto-detecting tmux or iTerm2 from your terminal
`iterm2`	iTerm2 native split panes explicitly (v2.1.186+); errors with an install hint if `it2` is missing

claude --teammate-mode auto sets it for one session. The flag is experimental and doesn’t show up in claude --help.

Steering the team

Teammates and models

Claude picks a team size from the task, or you spell it out:

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

Teammates do not inherit the lead’s /model choice by default — that’s the Default teammate model row in /config, where Default (leader’s model) makes them follow the lead. They do inherit the lead’s effort level (in split-pane mode from v2.1.186).

Plan approval

For risky work, make a teammate plan first. It stays in read-only plan mode until the lead approves:

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

Rejected plans come back with feedback and get revised and resubmitted. The lead decides on its own, so put your criteria in the prompt — “only approve plans that include test coverage”, “reject plans that modify the database schema”.

Talking to a teammate directly

Select it in the panel and press Enter (or click its pane in split mode). While you’re viewing an in-process teammate, plain text and skills go to that teammate, but built-in commands still run in the lead’s session.

Command	Where it lands
`/model`, `/fast`	The lead only — a teammate’s model and fast mode are fixed at spawn (v2.1.199 shows a notice)
`/effort`	The viewed teammate’s later turns, since teammates follow the lead’s effort level

Reusing subagent definitions

Spawn a teammate from any subagent definition — project, user, plugin, or CLI-defined — by naming the type:

Spawn a teammate using the security-reviewer agent type to audit the auth module.

The teammate honours that definition’s tools allowlist and model, and the body is appended to the teammate’s system prompt rather than replacing it. SendMessage and the task tools stay available even when tools is restrictive.

Shutting one down

Ask the researcher teammate to shut down

The lead sends a shutdown request; the teammate can accept and exit gracefully, or reject with an explanation. There’s no separate cleanup step — the shared directories go when the session ends.

Tasks and messages

The shared task list is the coordination surface. Tasks are pending, in progress, or completed, and can depend on other tasks — a pending task with unresolved dependencies can’t be claimed. The lead can assign explicitly, or a teammate self-claims the next unassigned, unblocked task when it finishes one. Claiming uses file locking so two teammates can’t grab the same task, and completing a task unblocks its dependents automatically.

Messaging is push, not poll:

Automatic delivery — messages sent between agents arrive without the lead polling.
Idle notifications — a teammate that stops notifies the lead. Since v2.1.198 a turn that ends on an API error reports the failure and error text instead of looking like a clean finish.
By name — any teammate can message any other by name. There’s no broadcast: to reach everyone, send one message per recipient. Tell the lead what to call each teammate if you want names you can reference later.

Each teammate loads CLAUDE.md, MCP servers, and skills like a normal session, plus the spawn prompt. The lead’s conversation history does not carry over, so put task-specific detail in the spawn prompt.

Hooks

Quality gates hang off three hooks; exiting with code 2 sends feedback back:

Hook	Fires when	Exit 2 does
`TeammateIdle`	A teammate is about to go idle	Sends feedback and keeps it working
`TaskCreated`	A task is being created	Prevents creation, sends feedback
`TaskCompleted`	A task is being marked complete	Prevents completion, sends feedback

The team_name field in these payloads carries the session-derived name and is deprecated.

Where it lives

Component	Role
Team lead	The main session — spawns teammates and coordinates
Teammates	Separate Claude Code instances working assigned tasks
Task list	Shared work items that teammates claim and complete
Mailbox	The messaging system between agents

The team name is derived from the session: session- plus the first eight characters of the session ID.

~/.claude/
- teams/
  - session-a1b2c3d4/
    - config.json
    - inboxes/
      - researcher.json
- tasks/
  - session-a1b2c3d4/

config.json holds runtime state — session IDs, tmux pane IDs, and a members array of names and agent IDs (the lead’s entry always carries the agent type team-lead). Teammates read it to discover each other. Don’t hand-edit or pre-author it; the next state update overwrites you. There is no project-level equivalent — a .claude/teams/teams.json in your repo is just an ordinary file.

The team config directory is removed when the session ends. The task directory persists, is never uploaded, and follows the same cleanupPeriodDays retention as session transcripts — so a resumed session keeps its tasks.

Permissions

Teammates start with the lead’s permission settings — including --dangerously-skip-permissions if the lead runs with it. You can change an individual teammate’s mode after spawning, but not per teammate at spawn time. Teammate permission prompts surface in the lead session, so approve them there.

When something goes wrong

The table below is about mistakes in how the team was set up. For what teams genuinely can’t do, see Limits.

Symptom	Fix
Teammates keep stopping on permission prompts	Pre-approve the tools they’ll need in `permissions.allow` before spawning — every prompt surfaces in the lead session and blocks that teammate until you answer
Deliverables overwrite each other	File ownership wasn’t assigned. Say which files each teammate owns, in the spawn prompt
One teammate sits idle while the others work	It has no task of its own, or a dependency never got marked complete. Give it work explicitly, or check the task list with `Ctrl+T`
Burning tokens faster than expected	Fewer teammates — cost is roughly linear in active ones. Three focused usually beat five scattered
Work disappears between steps	Have teammates write intermediate state to files as they go instead of holding it in context
The lead approves plans you’d have rejected	It decides on its own, so put explicit accept/reject criteria in the spawn prompt
A teammate is clearly going the wrong way	`Esc` interrupts it, `x` stops it. In split panes you see this in the first few turns instead of at the end

Limits

Limitation	What it means
No session resumption	`/resume` and `/rewind` don’t restore in-process teammates; the lead may message ghosts. Tell it to spawn new ones.
Task status lags	Teammates sometimes forget to mark tasks complete, blocking dependents. Update manually or nudge the lead.
Slow shutdown	A teammate finishes its current request or tool call first.
One team per session	Scoped to the session; no extra named teams, no sharing across sessions.
No nested teams	Teammates can’t spawn teammates. Only the lead manages the team.
No background subagents	An in-process teammate’s subagents run in the foreground; `run_in_background` or `background: true` returns an error.
Lead is fixed	The main session leads for its lifetime — no promoting or transferring.
Split panes need tmux or iTerm2	In-process works in any terminal.

Sizing and cost

Token usage scales roughly linearly with active teammates — each one is a separate Claude instance with its own context window. For research, review, and new feature work that’s usually worth it; for routine tasks a single session is cheaper.

Guideline	Why
3–5 teammates	Balances parallelism against coordination overhead; there’s no hard cap, but returns diminish
5–6 tasks per teammate	Keeps everyone busy and leaves the lead room to reassign if someone stalls
Self-contained tasks	A function, a test file, a review — too small and coordination costs more than it saves; too large and teammates run unchecked
One file owner	Two teammates editing the same file means overwrites — split work by file ownership

Dynamic workflows

When the plan belongs in a script instead of a lead’s context.

Tips

Subagents, context management, and git worktrees for parallel sessions.