Claude Code agent teams: what they are, when to use them

I have had CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in my user settings since the feature shipped. My machine has seven team directories under ~/.claude/teams/ from sessions since June. The production platform that writes content for two client operations has the same flag set in its container base settings. So I can tell you both what teams do and what they don't do, because I have paid for both.

Agent teams give each teammate its own context window and a mailbox. That's the entire feature. Everything else, the task list, the plan approvals, the split panes, is plumbing around those two facts. Whether you want that plumbing depends on one question: do the workers need to talk to each other, or only to you?

What an agent team actually is

A team is one lead session plus teammates that are each a complete Claude Code instance. Teammates load your CLAUDE.md, MCP servers, and skills like any session, but they don't inherit the lead's conversation.

The official agent teams reference, read on 2026-09-07, describes four parts: the lead, the teammates, a shared task list, and a mailbox per agent stored as a JSON file under ~/.claude/teams/{team-name}/inboxes/. The team name is derived from your session id, session- plus its first eight characters, and the config directory is deleted when the session ends. The task list under ~/.claude/tasks/ persists, so a resumed session keeps its tasks.

Two things surprised me when I re-read the current docs against my notes from February.

First, there's no setup step anymore. The TeamCreate and TeamDelete tools that early write-ups describe were removed in v2.1.178. Today Claude spawns a teammate by calling the ordinary Agent tool with a name while the flag is on. That's the whole trigger. It also means teams can form when you never asked for one: Claude names subagents on its own so it can message them later, and with the flag set, a named subagent becomes a teammate. The docs say this outright, and the fix is to set the variable to 0, which Claude Code reapplies to a running session when you save the settings file.

Second, the panel lies by omission. Subagents and teammates appear in the same agent panel, so seeing agents there doesn't mean a team formed. The session that wrote this article spawned six named agents. There's no team directory for this session at all, which is what the docs predict for a non-interactive session: the flag is set, no team formed, and every one of them ran as a plain subagent. If you need a team, ask for one explicitly and then check ~/.claude/teams/ for a directory named after your session.

Teams versus subagents versus workflows

Subagents report back to you and cost the least. Teams let workers coordinate among themselves and cost the most. Workflows move the orchestration into a script the runtime executes. Pick by who needs to hold the plan.

The docs' own comparison, condensed:

A Claude Code subagent does the side work in its own window and hands you a summary. That covers most delegation. The cases the docs list for teams are the ones where a summary isn't enough: parallel review with different lenses, debugging with competing hypotheses where teammates try to disprove each other, and cross-layer changes where each teammate owns different files. The recommendation is 3 to 5 teammates and 5 to 6 tasks each. Three focused teammates outperform five scattered ones, and that matches what I see.

There's a cost detail that matters more than the headline "uses more tokens." An in-process teammate's requests fall outside the main conversation's prompt cache bucket, so its cache holds for five minutes by default, on a subscription too. Set subagentPromptCacheTtl to 1h if a teammate will run long, and expect the 1-hour cache write to bill at a higher rate on the API.

How to start one and control it

Enable the flag, describe the roles, and let the lead spawn them. You can talk to any teammate directly, and the lead's permission settings apply to all of them.

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

Then a prompt like the one the docs use:

Spawn three teammates to review PR #142: one on security, one on
performance, one on test coverage. Have each review and report findings.

The lead breaks the work into tasks, spawns a teammate per role, and synthesizes when they finish. A finished teammate sends the lead an idle notification that carries its final answer. Before v2.1.251 that notification arrived empty, which is the kind of bug you only find by running the feature.

Model selection has a precedence order, and it changed in v2.1.251. The first of these wins: the model your spawn prompt names, then the model field of a subagent definition if the teammate was spawned from one, then CLAUDE_CODE_SUBAGENT_MODEL, then the lead's model. The old teammateDefaultModel setting is gone since v2.1.234 and a leftover value is ignored. Reusing subagent definitions for teammates is the practical way to keep roles stable: a security-reviewer file in .claude/agents/ works as both a delegated subagent and a teammate, though the definition's skills and, for in-process teammates, its mcpServers aren't applied.

Display mode defaults to in-process since v2.1.179. Split panes need tmux, or iTerm2 with the it2 CLI, and they don't work in VS Code's terminal, Windows Terminal, or Ghostty. Set teammateMode in settings or pass --teammate-mode for one session.

Permissions are where you should slow down. Teammates start with the lead's permission mode, and if the lead runs with --dangerously-skip-permissions, every teammate does. Teammate prompts surface in the lead session for you to answer. The one exception is plan approval: when a teammate spawned in plan mode finishes planning, the lead grants the plan without you reviewing it. Its edits still go through permission prompts, but the plan itself doesn't.

Messages between agents are labeled as coming from another Claude session. A teammate can't approve anything on your behalf, and a denied action can't be relayed through another teammate to get around the check. In auto mode the classifier reviews every inter-agent message before delivery.

The quality gate is a hook, not a prompt

Three hook events fire for teams: TeammateIdle, TaskCreated, and TaskCompleted. Exit with code 2 to send feedback and keep the teammate working, or to block a task from being created or marked done.

This is the same lesson as everywhere else in Claude Code. An instruction in a prompt is a suggestion. A hook that exits 2 is a rule. If you want a teammate to run the test suite before it goes idle, write a TeammateIdle hook that checks for a passing run and exits 2 with a message when it's missing. The teammate reads the message and keeps going.

The known limitations are honest and worth reading before you build on teams. /resume doesn't restore in-process teammates, and a resumed lead may try to message teammates that no longer exist. Task status can lag when a teammate forgets to mark a task complete, which blocks dependents until you nudge it. There's one team per session, no nested teams, the lead is fixed for the session, and an in-process teammate can't run its own subagents in the background because that work wouldn't survive the lead's process.

What we run in production, and why it isn't a team

The platform behind our AI agents for SEO case study has the agent teams flag set and never forms a team. Teammates can't spawn in Agent SDK sessions, and we deny the SDK's team messaging tool with a hook. Inside a pipeline, what runs is one level of foreground subagents passing files. Between pipelines, the platform has its own inter-agent layer, and that's the part that behaves like a team.

The docs state the SDK rule plainly: spawning teammates requires an interactive session, and in non-interactive mode, including the Agent SDK, a named subagent runs as an ordinary subagent even with the flag on. Our containers run on the Claude Agent SDK, so the flag in base-settings.json is inert there. We keep it because the same settings file serves interactive debugging sessions.

The SendMessage tool is a different story. It exists in SDK sessions, and the model sometimes reaches for it to deliver a response to the user. It routes into team messaging instead, so the content never arrives. A PreToolUse hook in our agent runner denies it and points the model at the delivery tool that actually reaches the channel. That hook exists because we lost responses before it did.

Here's the shape of the content pipeline on one of those servers, from the subagent definitions on disk. A topic-researcher runs on Sonnet and writes research.md. A draft-writer reads it and writes draft.md. The orchestrator runs an anti-AI-writing audit. A senior-editor then judges the draft against a fixed checklist and either passes it or sends it back, with at most two rewrite rounds before the piece is flagged for a human. An image-generator runs last. On the second server the editor is preceded by a deterministic contract validator that exits non-zero on structural violations before any model judgment happens, and an html-verifier runs twice, before and after upload. Every handoff is a file. No agent messages another agent.

Two guard hooks define this shape, and both were written after incidents.

The first forces every subagent spawn into the foreground. On 2026-08-13 two batches of background subagents were killed at exactly ten minutes with zero output, because the container's idle timer closed the container underneath them. The hook now denies any spawn that doesn't explicitly set run_in_background: false, on the reasoning that the SDK documents background as the default, so an omitted flag has to be treated as background.

The second blocks a subagent from spawning its own subagent. We observed a four-level cascade of general-purpose workers, all blocked on one shared state file, after a worker decided its task wouldn't fit in context and re-delegated the whole thing. One level of delegation is allowed. Workers are leaves.

The numbers, from the exported task records in the config repository: one content group on the first server holds 850 task records between 2026-05-08 and 2026-08-19, 846 of them completed. A second group holds 106, 96 completed. That's the throughput of a single-level, foreground, file-passing design. It's also the design the current docs recommend for sequential work with many dependencies, which is what a content pipeline is.

What we did build is inter-agent messaging one level up, between the agents themselves rather than between their subagents. Each agent on the platform is a full session bound to a channel, and it can send an asynchronous request to another agent with a cross_group_request that returns immediately; the reply comes back later through a cross_group_reply that only the target can call. A permissions table decides who may ask whom, deny by default, with exact and wildcard grants. A sweeper runs every 30 seconds and expires requests at five minutes by default and thirty at most, then posts the outcome back into the requester's conversation, distinguishing a request that timed out from one whose reply may have been delivered but couldn't be confirmed. Hops are capped at one, so an agent can't forward a request onward. That's a mailbox, a task status, and a permission boundary, which is the shape of an agent team, built at the platform layer so it works from SDK sessions where Anthropic's teams can't run. The content pipelines on disk don't call it today; the grants live in the database and are switched on per pair of agents when a workflow needs the handoff.

The same story played out on my own machine. On 2026-07-05 I dispatched seven general-purpose agents for a read-only audit. Each one inherited my rule that delegation runs in the background by default, so each one delegated onward instead of reading files, and every hop burned roughly 70k tokens producing nothing. The fix was structural, like the production hooks: read-only sweeps go to the built-in Explore agent, which runs with read-only tools and, in my setup, has no Agent tool to delegate with. The four currency checks that ran while I wrote this post used exactly that.

When I would actually use a team

Use a team when the value comes from workers disagreeing. Use subagents when the value comes from a clean summary. Use a workflow when the value comes from a rerunnable script.

The competing-hypotheses pattern is the strongest case in the docs and the one I reach for. When a bug has three plausible causes, a single agent finds one and stops. Five teammates told to disprove each other's theories converge on the survivor. That's a real capability and nothing else in the toolkit does it.

Parallel review with distinct lenses is the second case. Our own publishing process runs a fresh-context auditor on every post before it ships, and it has caught factual errors the writer and editor both missed. That auditor is a subagent because it only needs to report to me. If I wanted the auditor to argue with the writer, it would be a team.

Everything else, which is most of what I do, is subagents. Cheaper, simpler, and the results land where I can read them.

Frequently asked questions

Are Claude Code agent teams enabled by default?

No. Agent teams are experimental and disabled by default. Enable them by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your settings.json env block or your shell. Without it, no team directories are written and Claude doesn't spawn or propose teammates.

What is the difference between a subagent and a teammate?

A subagent runs in its own context window and returns a result to the caller. A teammate is a full Claude Code session that shares a task list with the team, messages other teammates directly, and keeps running across turns. Subagents cost less because their results are summarized back into your context.

Do agent teams work with the Claude Agent SDK?

No. Spawning teammates requires an interactive session. In non-interactive mode with the -p flag, including Agent SDK sessions, Claude doesn't spawn teammates, and a named subagent runs as an ordinary subagent even when the flag is set.

How many teammates should a team have?

The official guidance is 3 to 5 teammates for most workflows, with 5 to 6 tasks per teammate. Token cost scales linearly with the number of teammates because each has its own context window, and coordination overhead grows with team size.

Can a teammate approve a permission prompt?

No. Teammate permission prompts appear in the lead session for you to answer. A message from another agent never counts as your consent. The one designed exception is plan approval, which the lead grants automatically when a teammate finishes planning.