Claude Lessons / Guides

Claude Code Agent Teams: Run a Team of Claude Sessions in Parallel

Claude Lessons team · Updated August 18, 2026

Agent teams turn one Claude Code session into a team lead that spawns full, independent Claude instances — each with its own context window — coordinates them through a shared task list, and lets them message each other directly. It's the difference between delegating errands and running a standup. The feature is experimental, hidden behind an environment variable, and expensive when used carelessly; it is also the closest thing Claude Code has to genuine parallel collaboration, and for the right tasks (parallel code review, debugging with competing hypotheses) it beats a solo session decisively. This guide covers enabling it, when a team beats subagents, how coordination actually works under the hood, and the limitations you'll hit.

What agent teams are

An agent team has four parts: a lead (your main session, which spawns teammates and coordinates), teammates (separate, full Claude Code instances), a shared task list (work items teammates claim and complete, with dependencies), and a mailbox (a per-agent message queue on disk that agents use to talk to each other).

The properties that make this different from everything else in Claude Code:

• Teammates are whole sessions, not helpers. Each one loads your project context — CLAUDE.md, MCP servers, skills — exactly like a session you'd start by hand. What it does not get is the lead's conversation history: it knows what the spawn prompt tells it, and nothing else about what you've discussed.
• Communication is peer-to-peer. Teammates message each other directly by name, not just report upward. That enables genuinely new workflows — five agents actively trying to disprove each other's theory about a bug is not something a pile of isolated subagents can do.
• You can bypass the lead. Select any teammate in the agent panel and talk to it directly — redirect its approach, ask a follow-up, stop it. The lead coordinates, but it isn't a chokepoint.

Agent teams vs. subagents

Both parallelize work. The decision hinges on one question: do the workers need to talk to each other?

Rule of thumb: research-with-a-report → subagent. Review-with-a-debate, or a feature whose frontend, backend, and tests can proceed independently → team. Sequential work with many dependencies → neither; a single session with a good plan beats both. (If what you actually want is several isolated sessions that never interact, that's git worktrees, not agent teams — one worktree per session, no coordination overhead.)

Enabling agent teams

Agent teams are experimental and disabled by default. Enable them with one environment variable, either in your shell or in settings.json:

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

Three things to know before flipping it:

• No other setup remains. On current versions (v2.1.178+), spawning a teammate needs no create-a-team step, and cleanup happens automatically at session exit. Older writeups mention TeamCreate/TeamDelete tools — those no longer exist.
• Interactive sessions only. In claude -p and Agent SDK runs, Claude doesn't spawn teammates; a would-be teammate runs as an ordinary subagent even with the flag set.
• The flag changes ordinary delegation too. While enabled, a subagent that Claude names launches as a teammate — and Claude names subagents on its own. Teams can therefore form when you never asked for one. This matters because teammates report differently: a finished subagent returns its output to the caller, while a finished teammate only sends an idle notification (results arrive by message or the task list). An orchestration flow that waits on subagent results can stall. The fix is setting the variable to "0" — it takes effect on the next spawn without restarting the session.

Your first team, step by step

With the flag set, you just describe the team in natural language. A prompt that works well:

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings, then synthesize.

The lead populates the shared task list, spawns a teammate per role, and synthesizes when they finish. Teammates appear in the agent panel below the prompt input. The keys that matter:

Prompting details that improve results immediately:

• Name your teammates. "Spawn a teammate called reviewer…" gives you a stable name to reference later ("ask the reviewer to also check the auth module") instead of whatever the lead invents.
• Front-load context into spawn prompts. Teammates don't inherit your conversation. Everything you've explained to the lead — the bug's history, the constraint that matters — must be restated in the spawn prompt or the teammate works without it.
• Specify models if you want cheaper teammates. "Use Sonnet for each teammate" works; so does the CLAUDE_CODE_SUBAGENT_MODEL environment variable. Unspecified teammates run on the lead's model — at the lead's effort level.
• Check that you actually got a team. Claude sometimes chooses subagents instead; both appear in the same panel. If your workflow needs teammate messaging, ask again and explicitly request an agent team.
• Don't panic when idle rows vanish. Once the whole panel is idle, idle teammates hide after 30 seconds — they're still running and addressable. Message one by name and its row returns. More than three idle teammates collapse into a single "N idle agents" row; Enter expands it.

In-process vs. split panes

Set it with "teammateMode" in ~/.claude/settings.json or per-session with claude --teammate-mode auto. The values: "in-process", "auto" (split panes when you're already inside tmux or in iTerm2 with it2 installed, in-process otherwise), "tmux", or "iterm2". Two gotchas: the default changed to in-process in v2.1.179, so if your teams used to open panes and stopped, set "auto" explicitly; and split panes don't work in VS Code's integrated terminal, Windows Terminal, or Ghostty — in-process works everywhere.

How coordination actually works

Knowing the mechanics helps you debug a confused team instead of restarting it.

• The task list is the source of truth. Tasks are pending, in progress, or completed, and can depend on other tasks — a pending task with unresolved dependencies can't be claimed until they complete, and completing a blocker unblocks its dependents automatically. The lead assigns tasks, or idle teammates self-claim the next unblocked one. Claiming uses file locking, so two teammates can't grab the same task.
• Messages are files, delivered automatically. Each agent's mailbox is JSON at ~/.claude/teams/{team-name}/inboxes/{agent-name}.json; delivery is push, not polling. Team config lives at ~/.claude/teams/{team-name}/config.json (runtime state — don't hand-edit it) and the task list at ~/.claude/tasks/{team-name}/, under a session-derived name like session-a1b2c3d4. Config is removed at session end; the task list persists so resumed sessions keep their tasks.
• Idle notifications carry no output. When a teammate finishes, the lead learns it stopped — not what it found. Results move through messages or task updates. This is the root cause of most "the lead is ignoring my teammate's work" confusion.
• Reusable roles come from subagent definitions. A subagent you've defined (say, security-reviewer with a restricted tool list) can be spawned as a teammate by name; its tool allowlist and model are honored, and its body is appended to the teammate's system prompt. One definition serves both delegation styles.
• Plan approval adds a real checkpoint. Ask for it and a teammate starts in read-only plan mode, submits a plan, and only implements after the lead approves. The lead judges plans autonomously — so put your acceptance criteria in the prompt: "only approve plans that include test coverage." It's the team-scale version of the plan-first habit from our plan mode guide.
• Hooks give you programmatic gates. TeammateIdle fires when a teammate is about to go idle — exit code 2 sends feedback and keeps it working ("tests still failing, keep going"). TaskCreated and TaskCompleted can block task creation or completion the same way. Wire them like any other hook; see our hooks examples guide for the pattern.

Steering a running team

The failure mode of unattended teams isn't chaos, it's waste: a teammate stuck on an error, a lead that started implementing tasks itself, work drifting from the goal while nobody checks. Steering is the job you keep.

• Talk to teammates directly. In-process: select and press Enter, then type. Split panes: click into the pane. Plain text goes to the viewed teammate; built-in commands still run in the lead. /model and /fast only change the lead (a teammate's model is fixed at spawn); /effort does apply to the viewed teammate's later turns.
• Nudge the lead when it misbehaves. Two prompts fix the two classic failures: "Wait for your teammates to complete their tasks before proceeding" (lead doing the work itself) and "the team isn't finished — keep going" (lead declaring victory early).
• Revive or replace stalled teammates. A teammate that stopped after an error can be messaged with new instructions, or replaced ("spawn a replacement to continue the researcher's task"). A message also wakes a teammate waiting out an API retry delay.
• Shut down by name. "Ask the researcher teammate to shut down" sends a graceful shutdown request (the teammate finishes its current tool call first). Shared directories clean up when the session ends. If a tmux pane outlives everything, tmux ls and tmux kill-session -t <name> finish the job.

Permissions and safety

• Teammates inherit the lead's permission mode at spawn. All of it — a lead running with --dangerously-skip-permissions spawns teammates that skip permissions too. You can change an individual teammate's mode after it spawns, but not set per-teammate modes up front. Spawn teams from a session whose permission posture you'd accept multiplied by five.
• Permission prompts bubble up to the lead's terminal, and you answer them there. Five teammates hitting prompts gets noisy — pre-approve the routine operations in your permission settings before spawning, or run the team in auto mode and let the classifier do the reviewing.
• Auto mode reviews the team's chatter, too. The classifier screens every inter-agent message before delivery — including structured ones like plan approvals and shutdown requests — and treats one agent's claim that "the user approved this" as untrusted input rather than consent. A teammate that was denied an action can't launder it through a colleague. Messages from other agents are always labeled as coming from another session, never from you.
• Plan approval is the designed exception: the lead grants teammate plan approvals without prompting you. If you want eyes on plans, say so in your instructions to the lead — or review the diffs at the end, which you should be doing anyway.

When a team pays off — and when it doesn't

Token cost scales linearly with team size — each teammate is a full instance with its own context. So the question is always: does parallelism add information, or just add agents? Four patterns clear the bar:

• Parallel review with distinct lenses. Security, performance, and test coverage reviewers on one PR, simultaneously. A single reviewer gravitates to one class of issue; three scoped ones don't.
• Debugging with competing hypotheses. Spawn teammates on different theories and have them argue: "Have them talk to each other to try to disprove each other's theories, like a scientific debate." Sequential investigation anchors on its first plausible explanation; adversarial parallel investigation is the fix, and it's the single best demo of what teams can do that nothing else in Claude Code can.
• New modules with clean seams. Frontend, backend, and tests, each owned by a teammate who owns those files exclusively.
• Research fan-out with synthesis. Three libraries evaluated in parallel, findings challenged and merged — the lead synthesizes a comparison no single pass would produce.

Sizing guidance from the docs, which matches our experience: start with 3–5 teammates; give the lead 5–6 tasks per teammate; make tasks self-contained units with a clear deliverable. Skip teams entirely for sequential work, same-file edits, or anything routine — and if you're new to them, start with research and review tasks, which show the value without the merge conflicts. For the budgeting side of running several full contexts at once, see the token usage and costs guide.

Limitations and troubleshooting

Current limitations (this is an experimental feature and these change fast):

• No session resumption for in-process teammates. /resume and /rewind don't restore them; a resumed lead may message teammates that no longer exist. Tell it to spawn new ones.
• Task status can lag. Teammates sometimes fail to mark tasks completed, blocking dependents. Check whether the work is actually done, then update the task or have the lead nudge.
• One team per session, no nesting, lead is fixed. Teammates can't spawn their own teammates, you can't promote a teammate to lead, and a session has exactly one team scoped to it.
• Shutdown is graceful, therefore slow. Teammates finish their current request before exiting.
• File conflicts are your problem. Nothing stops two teammates from editing the same file; the last write wins. Partition ownership in the task descriptions.

And the diagnostic that solves most "it's not working" reports: teammates not appearing usually means the task was too simple to warrant a team (Claude decides), the panel hid idle rows (message a teammate by name to bring it back), or tmux isn't installed but split panes were requested (which tmux).

FAQ

What are agent teams in Claude Code?

Agent teams coordinate multiple full Claude Code instances working on one problem. Your session becomes the team lead: it spawns teammates, breaks work into a shared task list, and synthesizes results. Each teammate is an independent session with its own context window that loads your project context (CLAUDE.md, MCP servers, skills), claims tasks, and messages the lead and other teammates directly. Unlike subagents, teammates talk to each other — and you can talk to any of them individually.

How do I enable agent teams?

Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your shell or in settings.json under the env key, then describe the team you want in natural language. No other setup step exists on current versions; team directories are created at session start and cleaned up at exit.

What's the difference between agent teams and subagents?

Subagents run within your session, report results only to the main agent, and never talk to each other — cheaper and right for focused tasks where only the result matters. Teammates are fully independent sessions that share a task list and message each other — heavier, and right for work that benefits from discussion: parallel reviews, competing-hypothesis debugging, features with clean seams. When in doubt, start with a subagent; upgrade to a team when you catch yourself wanting the workers to compare notes.

Do agent teams use more tokens?

Yes — roughly linearly with team size, since every teammate carries a full context window. Worth it for parallel research, review, and independent feature work; not worth it for routine or sequential tasks. Using Sonnet teammates under an Opus lead ("use Sonnet for each teammate") is the easiest cost lever.

Why is Claude spawning teammates when I didn't ask for a team?

While agent teams are enabled, any subagent Claude names launches as a teammate — and Claude names subagents on its own. If that stalls a flow that waits on subagent results, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=0 in settings; it applies from the next spawn without a restart.

Can teammates work in the same files?

They can, and it ends in overwrites — task claiming is lock-protected, file editing is not. Give each teammate exclusive ownership of its files in the task descriptions, or keep implementation solo and use the team for research and review. For hard isolation between parallel sessions, git worktrees (one directory and branch per session) remain the manual alternative.