Claude Code Agent Teams Are Not Pointless

Agent teams are Claude Code's built-in way to run several full sessions as one crew: a team lead, teammates with their own context windows, a shared task list, and a mailbox per agent. The Claude Code documentation still labels them experimental as of August 2026, and they stay off until you set one environment variable.

Updated August 24, 2026 · by the AITerm team

What are agent teams in Claude Code?

An agent team is one Claude Code session acting as a lead, plus a set of teammates that are themselves full Claude Code instances. Each teammate has its own context window and loads your project context on spawn: CLAUDE.md, MCP servers, skills. What it does not get is the lead's conversation history, which is the single most common reason a teammate does something strange.

They coordinate two ways. A shared task list, where tasks move through pending, in progress and completed, and where a pending task with unresolved dependencies cannot be claimed until those dependencies clear. And a mailbox: a JSON file per agent under ~/.claude/teams/{team-name}/inboxes/, which is how one teammate addresses another by name without going through the lead.

You're probably thinking this is subagents with extra steps. It is not, and the difference is not philosophical. A subagent returns its result to the caller, so Claude reads what it produced. A teammate finishes and sends an idle notification that carries no output. If it did not message someone or update a task, the work exists in a context window nobody will ever read again.

Turns out that one asymmetry explains most of the confusion in the Reddit threads. People spawn a team, watch it finish, and find the lead cannot summarize what happened. Nothing broke. The findings were simply never sent anywhere.

Is Claude Code agent teams still experimental?

Yes, and it is worth saying plainly because none of the top-ranking pages date the claim. As of August 2026, the Claude Code documentation carries an explicit warning: agent teams are experimental and disabled by default. Without the variable set, no team is created at session start, no team directories are written, and Claude does not spawn or propose teammates at all.

// ~/.claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Before you turn it on, read the side effect, because it is the part that bites. Enabling teams also changes ordinary delegation. Claude names subagents on its own so it can message them later, and while teams are enabled, a named subagent launches as a teammate. Teams form in sessions where you never asked for one, and an orchestration that waits on subagent results stalls, because teammates report back with an idle notification instead.

And yes, there is an off switch, the same variable set to "0", and you do not need a new session: Claude Code reapplies settings-file env values when you save and rereads the variable each time it spawns a subagent. Watch the precedence though. A "0" in your user settings loses to a "1" in project settings, local settings or a managed settings payload.

The documented limitations are honest, and several of them will find you in the first hour. /resume and /rewind do not restore in-process teammates, so a resumed lead may try to message agents that no longer exist. Teammates sometimes fail to mark a task complete, which silently blocks everything depending on it. Shutdown waits for the current tool call to finish. A session gets exactly one team, teammates cannot spawn teammates, and the lead is the lead for the lifetime of the session.

The four moving parts

Strip the vocabulary away and a team is four things on disk plus a naming convention. Here they are, in the order you will meet them.

So, nothing here is magic. The interesting part is that all of it is inspectable with cat, which turns out to be the fastest debugging tool you have when a team goes quiet.

The team name is derived, not chosen: session- followed by the first eight characters of the session ID. That matters for cleanup, because the two directories behave differently.

# removed when the session ends
~/.claude/teams/session-a1b2c3d4/config.json
~/.claude/teams/session-a1b2c3d4/inboxes/reviewer.json

# persists locally, never uploaded, so a resumed session keeps its tasks
~/.claude/tasks/session-a1b2c3d4/

And yes, that asymmetry is deliberate. The task directory is swept on the same cleanupPeriodDays you already set for session transcripts. And do not pre-author the team config by hand: it holds runtime state like session IDs and tmux pane IDs, and your edits get overwritten on the next state update. A .claude/teams/teams.json in your project is not configuration either, Claude treats it as an ordinary file.

There is one composition trick worth knowing. A teammate can be spawned from an existing subagent definition in any scope, project, user, plugin or CLI, which means a role you already wrote once is reusable: spawn a teammate using the security-reviewer agent type to audit the auth module. The definition's tools allowlist and model apply, and its body is appended to the teammate's system prompt rather than replacing it. The catch: the skills and mcpServers frontmatter fields are ignored for teammates, which load those from your project and user settings like any session.

Watching five teammates is the actual job

Every guide on this feature stops at the spawn prompt. That is the easy half, and it was never the problem. The hard half starts four minutes later, when five agent sessions are running and you cannot tell which one is blocked, which one went quiet because it finished, and which one went quiet because it hit an API error.

Claude Code ships a real answer in-process. The agent panel sits below the prompt input: arrow keys select a teammate, Enter opens its transcript so you can message it directly, Escape interrupts its current turn, x stops it, and Ctrl+T toggles the task list. Worth knowing before you panic: an idle teammate's row hides 30 seconds after the whole panel goes idle, and when more than three are idle the surplus rows collapse into a single 2 idle agents row. A hidden row is not a dead teammate. It is still running and still addressable by name.

Split panes are the other option, one pane per teammate, and they require tmux or iTerm2 with the it2 CLI installed. The default changed to "in-process", so upgraded sessions that used to fan out into panes now stay in one terminal unless you say otherwise:

# per session, experimental, absent from claude --help
claude --teammate-mode auto

# or permanently, in ~/.claude/settings.json
{ "teammateMode": "auto" }

Here's the thing. Split-pane mode is not supported in VS Code's integrated terminal, in Windows Terminal, or in Ghostty. So the moment you want five agent sessions side by side, Google's own AI Overview and the docs both hand you the same answer: install tmux. In 2026. To watch five processes on a laptop.

Fair question: why did we build a product around this instead of learning the tmux keybindings? Because the state you need is not only per teammate. It is per provider, per project and per pane, and it has to be visible without typing a command or attaching to a session. Our cockpit shows the three states you actually think in, needs attention, working, ready, next to the live quota windows for each provider. Five teammates on one 5 hour window is exactly the case where the window is the thing that kills the run, not the machine.

Honestly, we learned this one the expensive way. We shipped a Maestro build with agent teams enabled by default in the bundled settings, and our orchestration kept stalling on a step that waited for a subagent result. There was no bug in our code. Named subagents were launching as teammates, and a teammate returns an idle notification with no output in it, so the step waited forever for something that structurally could not arrive. We spent the better part of two weeks calling it a flaky fleet. It was a one-line default we set ourselves.

What does a five session team cost your machine?

Nobody publishes this number, so here is ours. Same M2 Air with 16 GB, same repository, cold start each time, one prompt of comparable size per session, measured while every session was actively generating rather than idling. A lead plus four teammates is five Claude Code sessions.

Look, the honest headline is that your laptop is fine. Five sessions on a 16 GB machine leaves room to work, the machine stays responsive, and typing latency in our panes stayed under 8 ms with all of them streaming, because the rendering is native rather than a browser engine per window. Anyone telling you agent teams need a bigger machine is measuring the wrong thing.

The real bill is tokens, and the multiplier is not subtle. Anthropic's cost documentation puts agent teams at approximately seven times the tokens of a standard session when teammates run in plan mode, because each one is a separate instance carrying its own context. For scale, the same page reports average enterprise usage around 13 dollars per developer per active day, staying under 30 dollars for 90% of users. Multiply that by seven and you understand why the Reddit thread is titled the way it is.

In practice, the number you budget is not memory. It is a window. On a subscription plan, five teammates working in parallel empty a 5 hour usage window fast, and the window refills on a clock you do not control. There is a quieter multiplier too: every session sends its full conversation with each request, and the prompt cache lifetime is one hour on a subscription, dropping to five minutes once you are drawing on usage credits. Five teammates you left alone for ninety minutes is five cache misses when you come back.

Teams, subagents or worktrees

Honestly, this is where most of the writing on the subject goes quiet, because settling it takes measurement rather than opinion. Three mechanisms parallelize Claude Code and they are not interchangeable. The token curve is the fastest way to see it.

Here is the call we make. Use subagents when only the answer matters and one worker can produce it: run the tests, read the docs, grep the codebase, hand back a summary. Use worktrees when several agents must write to the same repository without colliding, because agent teams give you no file isolation at all and two teammates editing one file simply overwrite each other. Use agent teams when the value is in the disagreement.

That last one deserves a real example rather than a slogan. In July we put four teammates on the review of our pane renderer rewrite, roughly 2,400 changed lines. One on security, one on performance, one on test coverage, and one whose entire brief was to argue with the other three. They produced 11 findings, of which 6 held up under a second look, and the two that actually changed the design came from the contrarian. The same diff reviewed by a single session, same model, same prompt budget, produced 4 findings and missed both of them.

In practice, that is the whole case for agent teams, and it is narrower than the marketing around them suggests. Parallel exploration with adversarial pressure finds things sequential exploration does not, because a single agent anchors on the first plausible explanation and stops looking. Anthropic's own documented example for this is five teammates chasing competing hypotheses on a bug and trying to disprove each other, and it works for the same reason.

How do you properly use Claude Code agent teams?

Start read-only. A pull request review, a library investigation, a bug with several plausible causes. Anthropic's own guidance says the same thing, and the reason is not caution, it is that read-only work has no merge phase, so nothing you gained in parallel gets spent back at the end.

So, a handful of things that changed our results more than any prompt tuning did. Name the teammates explicitly in your spawn instruction, because you will want to address them by name later and the lead otherwise picks its own. Put the task detail in the spawn prompt, since teammates get your project context but not the lead's conversation. Split the files before you split the work.

Spawn three teammates to review PR #142. Call them sec, perf and tests.
sec: token handling and session management in src/auth/ only.
perf: the render path in Sources/AITerm/Pane/ only.
tests: coverage of the two directories above, nothing else.
Have each report findings to me with a severity, then stop.
Require plan approval before any of them edits a file.

Plan approval is underused. Ask for it and the teammate works in read-only plan mode until the lead approves, and if the lead rejects, the teammate revises and resubmits without leaving plan mode. The lead decides alone, so give it a rule in your prompt if you care about the outcome: only approve plans that include a regression test is a sentence that pays for itself.

Turns out hooks are the other lever, and almost nobody mentions them. TeammateIdle fires when a teammate is about to go idle, and exiting with code 2 sends it feedback and keeps it working, which is the clean fix for teammates that stop early. TaskCreated and TaskCompleted work the same way: exit 2 to block the transition and explain why. That is how you enforce a rule like "no task gets marked complete without a passing test run" across a whole team instead of repeating it in every prompt.

And shut them down when they are done. Ask the lead to shut a teammate down by name, since the teammate can approve or reject with an explanation. An active teammate keeps consuming tokens until it exits or the session ends, and a forgotten idle teammate whose row hid itself 30 seconds ago is the easiest way to burn a window on nothing.

The traps that cost us the most

Six weeks of running teams on real work, condensed. None of these are exotic, and all of them cost us at least an afternoon. Honestly, the pattern across all seven is the same: a team fails quietly, and you find out twenty minutes later.

Our own number, for what it is worth: the median in our anonymous daily ping is three simultaneous agent sessions per user, with the tail above six sitting under 10%. We cap our own Maestro fleet at four, and we run teams of two when the work involves writing code. Not because five does not work, but because past two writers the merge conversation costs more than the parallelism saved. Conflict surface grows with the number of pairs of agents touching related files, and four agents is six pairs.

The short version: turn agent teams on for review, investigation and anything where you want the agents to argue. Turn them off for implementation, where subagents are cheaper and worktrees are safer. And whatever you run, solve the watching problem first, because that is the one no flag fixes. That's it.

Going further

Sources

1. Orchestrate teams of Claude Code sessions, Claude Code documentation, 2026: the experimental warning and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS variable, the lead, teammates, shared task list and mailbox architecture, the ~/.claude/teams/ and ~/.claude/tasks/ paths and session-derived naming, file-locked task claiming, the agent panel keys and idle-row hiding, teammateMode and --teammate-mode, plan approval, permissions at spawn, subagent definitions as teammate roles, the three to five recommendation, and the full limitations list.
2. Manage costs effectively, Claude Code documentation, 2026: agent teams at approximately seven times the tokens of a standard session in plan mode, roughly 13 dollars per developer per active day with 90% under 30 dollars, the guidance to use Sonnet for teammates and shut them down when done, and the one-hour prompt cache lifetime that drops to five minutes on usage credits.
3. Subagents, Claude Code documentation, 2026: isolated context windows, results summarized back to the caller, the isolation: worktree and background: true frontmatter fields, the tools allowlist and disallowedTools denylist, model resolution order, and where definitions live under .claude/agents/.
4. Run parallel sessions with worktrees, Claude Code documentation, 2026: the --worktree flag and the isolation checks that agent teams do not apply to teammates.
5. Hooks reference, Claude Code documentation, 2026: the TeammateIdle, TaskCreated and TaskCompleted hooks and the exit code 2 behavior that sends feedback and blocks the transition.
6. Settings, Claude Code documentation, 2026: settings precedence across user, project, local, --settings and managed sources, which decides whether your "0" actually wins.
7. Cross-session messaging, Claude Code documentation, 2026: how a session treats a message from another Claude Code session, and the alternative to a team when you only need two sessions to talk.
8. Permission modes, Claude Code documentation, 2026: auto mode, and the classifier checks applied to messages between agents so a relayed approval claim is treated as untrusted input.
9. r/ClaudeCode, 2026: the thread titled "Convince me that agent teams are not pointless", which ranks in the top three of the Google results for this feature and frames the skepticism this article answers.
10. You probably don't need Claude agent teams (but here's when you do), Builder.io, 2026: the community counterpoint arguing teams are the wrong tool for a bug fix or a refactor and the right one for parallel review and competing hypotheses.
11. it2, mkusaka: the iTerm2 CLI that split-pane teammate mode requires, alongside the Python API toggle in iTerm2 settings.
12. tmux wiki: installation of the terminal multiplexer that split-pane mode falls back to, and which the docs recommend entering through tmux -CC in iTerm2.