Agent Teams: Coordinated Peer Sessions

You already know subagents: helpers that run inside your one session, do isolated work, and report a summary back. You may also know dynamic workflows: a script that fans hundreds of subagents out, holding intermediate results in script variables. Both share one limitation by design — the agents never talk to each other. A subagent hands a summary up to the parent; a workflow stitches strings together with pure concatenation. There is no message bus in either.

Agent teams is the paradigm that breaks that rule. It is multi-session peer collaboration: a lead session (your main Claude Code session) spawns several independent teammate sessions, each a separate Claude Code instance with its own full, fresh context window. They coordinate through two shared resources you don't get anywhere else: a shared task list they claim work from, and a mailbox through which they send each other real messages. Teammates self-coordinate around the tasks rather than reporting up to a parent.

        ┌──────────────────────────────────────────┐
        │  LEAD session (you drive this one)         │
        └───────────────┬────────────────────────────┘
           spawns        │   shared task list  +  mailbox
        ┌────────────────┼─────────────────┐
        ▼                ▼                 ▼
  ┌───────────┐   ┌───────────┐    ┌───────────┐
  │ Teammate A│   │ Teammate B│    │ Teammate C│   each = full,
  │ full ctx  │◄─►│ full ctx  │◄──►│ full ctx  │   fresh context
  └───────────┘   └───────────┘    └───────────┘   window
      claim tasks · message each other · self-coordinate

The trade is plain: every teammate is a full context window, so this is the most expensive paradigm per agent — but it's the only one where agents divide a fuzzy problem and hand off to one another. That's the thing to reach for when the work isn't a clean fan-out but a genuine collaboration.

Because agent teams is experimental and off by default, you must opt in explicitly. Set the environment variable, either in your shell or in a settings.json env block:

# Shell (current session)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

// ~/.claude/settings.json — persistent across sessions
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

That's the whole switch. Once enabled, your normal Claude Code session becomes capable of acting as a lead: you ask it (in plain English) to create a team and spawn teammates, and it provisions the independent sessions for you. The variable gates the feature entirely — with it unset, none of the team tools or commands exist.

Require v2.1.32+; check with claude --version. If the team commands don't appear after setting the variable, you're likely on an older build.

A team has four moving parts, three of which live on disk so independent sessions can share them.

The lead. Your main session. It is fixed — there is no promoting a teammate to lead and no transferring lead to another session. The lead provisions teammates, can assign tasks, and is the only session allowed to clean the team up.

The teammates. Separate Claude Code instances, one per role. Each has its own complete context window and runs independently — it is not a subagent living inside the lead.

The shared task list. Stored at ~/.claude/tasks/{team-name}/. Tasks move through three states — pending → in-progress → completed. Dependencies are managed automatically (a task blocked on another won't be claimable until its prerequisite completes), and file locking prevents two teammates from grabbing the same task at once.

The mailbox. The inter-agent messaging channel — how teammates and the lead actually send each other text, not just status. This is the piece that makes a team a team.

Configuration lives at ~/.claude/teams/{team-name}/config.json. It is auto-generated — its members array tracks each teammate's name, agent ID, and agent type. Do not hand-edit it; let the lead manage it. And there is no nesting: a teammate cannot spawn its own team or further teammates. One lead, one flat team.

~/.claude/
├── tasks/
│   └── {team-name}/        ← shared task list (pending/in-progress/completed)
│                              auto dependencies + file locking
└── teams/
    └── {team-name}/
        └── config.json     ← AUTO-GENERATED members array; do NOT hand-edit

Because teammates are separate sessions, you need a way to see and talk to them. There are two display modes, plus an auto default that picks for you.

in-process — all teammates run inside your main terminal. You cycle between them with Shift+Down. This mode works anywhere, in any terminal, with no extra tooling. It's the safe default.

tmux split panes — each teammate gets its own visible pane; you click a pane to interact with that teammate. This needs a terminal multiplexer: tmux, or iTerm2 with the it2 CLI installed. It's the richer view when you want to watch several teammates at once.

auto (the default) uses split panes if you're already inside tmux, and falls back to in-process otherwise.

Set the mode with teammateMode in settings.json, or the --teammate-mode in-process|tmux flag at launch.

Split-pane mode is NOT supported in the VS Code integrated terminal, Windows Terminal, or Ghostty. In those, use in-process (or run inside tmux).

You don't script a team — you talk to the lead in plain English, and it provisions and coordinates the teammates. The vocabulary:

Create + spawn. "Create an agent team to migrate our API to v2. Spawn three teammates: a migrator, a test-writer, and a reviewer." The lead sets up the team and the independent sessions.

Spawn from a subagent definition. You can name an existing subagent type: "Spawn a teammate using the security-reviewer agent type." When you do, the definition's system prompt + tools allowlist + model carry over to the teammate. But there's a sharp caveat (below): the definition's skills and mcpServers do NOT apply — teammates load those from project/user settings instead. Team-coordination tools (sending messages, task management) are always available to a teammate even if the definition restricts its tools.

Assign or claim. The lead can assign a task to a specific teammate, or teammates can self-claim any unblocked (dependency-satisfied) task from the shared list.

Talk to a teammate. Switch to it — Shift+Down in in-process mode, or click its pane in split mode — and type.

Shut down gracefully. The lead sends a shutdown request; the teammate approves its own exit (this can be slow — see limitations).

Clean up — from the lead. "Clean up the team." This removes the shared resources (task list, config, sessions) consistently. Cleanup MUST run from the lead, not a teammate — running it elsewhere won't tear things down cleanly.

Left alone, agents declare victory once work looks finished. Agent teams give you three team-specific hooks to wire deterministic gates around the task lifecycle. Each is a shell command; exit code 2 is the lever — it sends feedback and either blocks the transition or keeps a teammate working.

The canonical use is TaskCompleted as a quality gate: a teammate tries to mark a task done; your hook runs the test suite (or a security scan, or a docs check); if it fails, the hook exits 2, the completion is blocked, and the teammate gets told what to fix. "Done" now provably means tests pass — not just that the teammate believes it's finished.

#!/usr/bin/env bash
# TaskCompleted hook: block 'done' unless tests pass
if ! npm test --silent; then
  echo "Tests failing — task is not complete. Fix and re-run." >&2
  exit 2   # blocks completion + sends this feedback to the teammate
fi
exit 0

TeammateIdle is the counterpart for the other failure mode — a teammate quitting while there's still claimable work; exit 2 nudges it back to the task list.

Cost scales linearly with concurrent teammates. Every teammate is a full context window running independently, so two teammates cost roughly twice one, three cost three times, and so on — there's no context-sharing discount the way subagents (summaries) or workflows (script variables) give you. This makes teams the most expensive per-agent paradigm. The practical sizing: 3-5 teammates, ~5-6 tasks each, and don't leave a team running unattended — costs accrue while you're away and there's no auto-stop.

How far can it go? Anthropic's engineers used coordinated Claude Code sessions to build a C compiler — roughly 2,000 sessions over about two weeks, ~$20,000 in API cost, producing a ~100,000-line compiler that builds Linux on x86/ARM/RISC-V. Treat that as an order-of-magnitude anecdote, not a target: it shows the ceiling of what coordinated sessions can do, and how the cost scales when you push it.

Known limitations (be honest with yourself):

• It's experimental — expect rough edges.
• /resume and /rewind do NOT restore in-process teammates — restoring a session won't bring its teammates back.
• Task status can lag — teammates sometimes fail to mark a task complete; nudge them manually.
• Shutdown is slow — graceful exit requires the teammate to approve, which takes time.
• One team at a time per lead — you can't run multiple teams from one lead.
• No nested teams, no lead transfer — the structure is flat and the lead is fixed.