skip to content

When do you use Claude Code agent teams instead of subagents, how do you turn them on, and how do you stop teammates overwriting each other's files?

level: seniorimportance: should knowfreq 11%

answer

  1. experimental, off by default
  2. an environment variable set to 1
  3. a lead, teammates, tasks, a mailbox
  4. teammates talk to each other directly
  5. no worktree per teammate: own the files

basics

~20 s

Agent teams are experimental and enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Use them when workers must talk to each other and share a task list, not just report back; teammates get no worktrees, so give each one its own files.

solid answer

~50 s

Subagents work inside one session and return a result to the caller; agent teams are separate Claude Code sessions, a **lead** plus **teammates**, that message each other by name through a mailbox and, when they have the task-list tools, claim work from a **shared task list**. Choose a team when workers need to share findings, challenge each other or coordinate across layers; choose subagents for focused jobs where only the result matters, since each teammate is a full instance and tokens scale with team size. Teams are experimental and off by default: set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to `1` in the shell or a settings file's `env`, in an interactive session. Teammates are not isolated in worktrees, so two editing one file overwrite each other; partition the work so each owns a different set of files. Task claims use file locking, but that guards the task list, not your source files.

code

json · 5 lines
json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

go deeper

for a junior

Know that agent teams are experimental, off by default, and switched on with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS set to 1.

for a middle

Explain the lead, teammates, shared task list and mailbox, and how a team differs from subagents in communication and token cost.

for a senior

Show the conflict model: teammates share the lead's checkout, claims are locked but files are not, so partition ownership and watch for named subagents silently becoming teammates.

for a principal

Judge when a team's extra tokens and coordination buy enough parallel insight, and when subagents, worktree sessions or one session would deliver the same result more cheaply.

## What an agent team is An **agent team** is several Claude Code sessions working together. One session is the **team lead**: it spawns teammates, creates and assigns tasks and synthesizes results. Each **teammate** is a separate, full Claude Code instance with its own context window. The pieces: | Component | Role | |---|---| | Team lead | the main session; fixed for its lifetime | | Teammates | independent instances working on assigned tasks | | Task list | shared work items with states pending, in progress and completed, plus dependencies | | Mailbox | per-agent message files that deliver messages automatically | Teams are **experimental and disabled by default**. Without the switch, no team is set up and Claude neither spawns nor proposes teammates. ## Turning them on Set the environment variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to `1`, either exported in your shell or in a settings file's `env` block. Then ask for teammates in plain language, for example three reviewers with distinct lenses. Two conditions catch people out: - **Interactive only**: with `-p`, including Agent SDK sessions, Claude does not spawn teammates; a named subagent runs as an ordinary subagent. - **Teams can form unasked**: while the variable is on, a subagent that Claude names launches as a teammate, unless the call is a fork or passes `isolation` on the call itself. Setting the variable to `0` restores ordinary named subagents. Display is separate from enabling: `teammateMode` (or `--teammate-mode`) picks `in-process`, the default, or split panes through tmux or iTerm2. ## Teams against subagents | | Subagents | Agent teams | |---|---|---| | Context | own window; result returns to the caller | own window; fully independent | | Communication | report back to the caller | teammates message each other by name | | Coordination | the main agent manages everything | messages plus a shared task list | | Token cost | lower: summaries return | higher: every teammate is a full instance | Use a team for research and review from several angles, competing debugging hypotheses, or a feature split across frontend, backend and tests. Use subagents, or one session, for sequential work, same-file edits or tasks with many dependencies. Teammates load project context, CLAUDE.md, MCP servers and skills, plus the lead's spawn prompt, but **not the lead's conversation history**, so the spawn prompt must carry task detail. ## How the shared task list works 1. The lead breaks the work into tasks; a task with unresolved dependencies cannot be claimed until they complete. 2. The lead assigns tasks, or a teammate that finishes one **self-claims** the next unassigned, unblocked task. 3. **File locking on the claim** stops two teammates taking the same task at once. 4. Completing a task unblocks its dependents automatically. Hooks can gate this: `TaskCreated`, `TaskCompleted` and `TeammateIdle` exiting with code 2 block creation or completion, or keep a teammate working, with feedback. ## Stopping file conflicts The lock protects task claims, **not your source tree**. Agent teams do not give teammates worktrees, so they edit the same checkout. Two teammates editing the same file leads to overwrites. The practical rules: - **Partition by file ownership**: each teammate owns a distinct set of files or modules, stated in its spawn prompt. - **Size tasks as deliverables**: a function, a test file or a review, with roughly five or six tasks per teammate. - **Start small**: three to five teammates for most work. - **Do not rely on frontmatter isolation**: when Claude names a subagent and it launches as a teammate, an `isolation: worktree` line in that subagent's definition does not stop it; the teammate runs in the main session's working directory. ## Steering a running team In the default in-process display, teammates appear in an agent panel below the lead's prompt: - **Up and down arrows** select a teammate, and **Enter** opens its transcript so you can message it directly. - **Ctrl+T** toggles the task list, and **x** stops the selected teammate. - To end a teammate gracefully, ask the lead to shut it down by name; the teammate can accept or decline with a reason. - If the lead starts implementing tasks itself instead of waiting, tell it to wait for its teammates. The team's config directory is removed when the session ends, while the task list directory persists locally so a resumed session keeps its tasks. ## Permissions and limits Teammates start in the lead's permission mode (except `dontAsk`), and their permission prompts surface in the lead's session. A message from a teammate is never treated as your consent. Current limitations include: `/resume` and `/rewind` do not restore in-process teammates, one team per session, no nested teams, and a lead that cannot be replaced.

  • With agent teams enabled, Claude keeps spawning teammates when you wanted ordinary subagents. Why, and how do you stop it?
    While the variable is on, any subagent Claude names launches as a teammate, unless the call is a fork or passes `isolation` itself, and Claude names subagents on its own to message them later. Set `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` to `0` in settings; Claude Code rereads it at each spawn, so no restart is needed, though a higher-precedence source can still set it to `1`.
  • You resume yesterday's session and the lead keeps messaging teammates that never answer. What happened?
    That is a documented limitation: `/resume` and `/rewind` do not restore in-process teammates, so after a resume the lead may address teammates that no longer exist. Tell the lead to spawn new teammates, and keep the needed context in the task list and spawn prompts rather than in teammates' memories.
  • Where do a teammate's permission prompts appear, and can another teammate approve them?
    They surface in the lead's session for you to approve. A teammate cannot approve a prompt or supply consent for you, and one denied an action cannot relay it to another teammate to bypass the check; Claude Code marks inter-agent messages as coming from another Claude session, not from you.

Subagents are contractors who each report to one manager; an agent team is a squad with a shared task board and a group chat. The board stops two people grabbing the same ticket, but not two people editing the same document, so each document needs one owner.

  • Agent teams are on by default whenever Claude spawns more than one subagent.
  • Teammates inherit the lead's conversation history, so a short spawn prompt is enough.
  • Each teammate gets its own git worktree, so file conflicts cannot happen.
  • isolation: worktree in a subagent's frontmatter keeps it isolated when it launches as a teammate.
  • Agent teams work the same in claude -p pipelines as in interactive sessions.
  • The task list's file locking stops two teammates editing the same source file.