Claude Code Agent Teams: Setup, a Real Test, and When They're Worth It
Agent teams let one Claude Code session act as a lead that spawns teammates, each in its own context, who share a task list and message each other. They're experimental: set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 and ask for a team in an interactive session. We ran two tests. Three reviewers found 24 issues in an invoice module where one session found 12, at seven times the token cost. Two builders, each owning one file, fixed the rounding without a single collision.
Tested by us on 11 November 2026.
Turn agent teams on
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}In ~/.claude/settings.json, or export the variable in your shell.
- Interactive only. With
claude -p, Claude doesn't spawn teammates; named helpers run as ordinary subagents. - Teams can form on their own. While the setting is on, a helper Claude names launches as a teammate, even if you didn't ask for a team.
- Display. By default teammates run inside your terminal; arrow keys pick one in the agent panel, Enter opens it. Split panes need tmux or iTerm2.
- Limits. One team per session, no nested teams, and
/resumedoesn't bring in-process teammates back.
Our test: three reviewers on one invoice module
We wrote a 15-line Python module with four functions (invoice number, due date, total with VAT, reminder check) and two passing tests. Then we started Claude Code 2.1.321 interactively with agent teams on, in auto mode, and sent this prompt:
Create an agent team to review factuur.py before we use it for real invoices. Spawn three teammates: one checks the VAT and rounding math, one checks dates and reminders, one checks the tests. Each reports problems with a severity. Don't edit any files. When all three are done, give me one combined list.The lead created three teammates named vat-math, dates-reminders and tests-review, waited for all three and merged their reports into one list: 2 critical, 6 high, 9 medium and 7 low. All three reviewers ran small pieces of code to prove their points, and nobody edited a file. /usage reported 1 minute 18 seconds of model time and $0.35 in token cost.
Team versus one session
We then gave one ordinary session the same review in one prompt, without a team.
| Agent team (lead + 3) | One session | |
|---|---|---|
| Setup | Interactive session, auto mode, Sonnet 5.5 for lead and teammates | claude -p, auto mode, Sonnet 5.5 |
| Findings | 24: 2 critical, 6 high, 9 medium, 7 low | 12: 3 high, 5 medium, 4 low |
| Model time | 1 min 18 s | 17 s |
Token cost (from /usage and the JSON result) | $0.35 | $0.05 |
| Found the date/datetime crash | Yes, by running it | No |
| Found the float rounding bug | Yes, with two examples | Yes, with one example |
Count the findings by weight and the gap shrinks. Both found the rounding bug, the missing per-line VAT rates and the thin tests. The team rated the missing tests as critical; the single session called them medium. Most of the team's extra items were real but small: test hygiene, a shadowed parameter name, the invoice year around New Year. One finding separated the two on substance: give the reminder check a due date with a time in it and it crashes with a TypeError. We checked that one and the rounding bug with Python on a Windows PC, and both held.
(opens at full size)Second test: two builders, one file each
Review is the easy case, because nobody writes. So we also had a team change code, with the rule that prevents collisions: one owner per file. The prompt named two teammates. code could change only factuur.py, to switch the total to Decimal with half-up rounding. tests could change only test_factuur.py, adding tests including 5 × €0.50 at 21% giving 3.03.
Both finished in 52 seconds of model time and $0.18 in tokens. Neither touched the other's file, and the lead ran the suite afterwards: 10 tests, all passing. The lead also caught what ownership can't prevent. The total now returns a Decimal instead of a float, so every caller has to change. Splitting files stops overwrites; it doesn't stop one teammate from changing what the other depends on. Put the shared interface in the spawn prompt.
When a team is worth it
- Yes: reviews and research where separate angles find different things, like our three reviewers. Anthropic recommends starting there, because nobody edits files.
- Yes: new features with clearly separate parts, such as front end, back end and tests, each owned by one teammate.
- No: sequential work, small fixes, or two people editing the same file. A single session or a subagent is cheaper and avoids overwrites.
- Size: we tested teams of two and three; both stayed easy to follow. Anthropic suggests three to five teammates with five or six tasks each. We haven't tested five, so we'd start with two or three and add one only when a separate angle is missing.
How we split parallel work
We run many agents side by side outside Claude Code's team feature, as separate workers with a coordinator. In five weeks that came to 441 groups of parallel workers. Three rules carry most of the weight. Every worker writes only in its own folder; changes elsewhere arrive as a patch with a note. Workers never deploy, restart or send anything; the coordinator does that after checking. And when the last worker in a group finishes, the coordinator gets a fresh turn with a task written down in advance: merge, test, deliver.
Goal: <one sentence>
You write ONLY in: <folder>. Changes elsewhere: deliver a patch in your folder, with a note.
Don't: deploy, restart, email, publish.
Done = <measurable check>. Final report: first line "Done." or "Not done: <reason>".The first lines of every task we hand to a parallel worker. They work as a spawn prompt for a teammate too.
We also cap how many agents run at once and check free memory before each new one starts. On one server in October 2026, too many agents at once got processes killed. Since then new agents wait in a queue instead.
Questions
How do I enable agent teams in Claude Code?
Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1 in your settings or shell, start an interactive session and ask Claude to create a team with the teammates you want.
What's the difference between agent teams and subagents?
Subagents report back to the main session and don't talk to each other. Teammates share a task list, message each other directly and can be addressed by you one by one. Teams use more tokens.
How much do agent teams cost?
Each teammate is a full session with its own context, so cost grows with team size. In our test, a lead with three reviewers used about seven times the tokens of one session doing the same review.
Do agent teams work with claude -p?
No. Teammates only spawn in interactive sessions. In -p mode, named helpers run as regular subagents.
Sources
- Claude Code docs: Orchestrate teams of Claude Code sessions checked on
- Claude Code docs: Subagents checked on
- Claude Code docs: Costs (agent team token costs) checked on
More in claude in practice
- Claude Code Commands: The Cheat Sheet We Use Every DayThe Claude Code commands, flags and shortcuts worth learning first, on one printable cheat sheet, plus how to make your own slash command. Tested Nov 2026.
- Claude Code Hooks: Five Examples You Can Copy, TestedFive Claude Code hooks with full code: block dangerous commands, protect secrets, add a house rule, log every tool call, refuse to stop on failing tests.
- Claude Code Auto Mode: What It Allows, What It Blocks, and What We Learned in 9 TestsWe ran nine tasks in Claude Code auto mode, risky ones included. What it let through, what stopped them, and the deny rules we'd add first.
- Claude Code in a Loop: /loop, the Ralph Loop, and When a Long Job Needs Something ElseClaude Code's /loop, the Ralph loop and long-running jobs compared. We ran six tasks as a loop and as one session: same result, four times the cost.
Also useful
- AGENTS.md Explained: One Instruction File for Codex, Claude Code and Other AgentsAGENTS.md is the shared instruction file for coding agents. How Codex reads it, when Claude Code does, and the one-line fix we tested.
- AI for project managers: minutes, status reports and a critical path, each tested three timesMinutes, a status report and a critical path, each run three times. Where AI was right every time, its one invented claim, and a weekly report setup.
- How to Build an MCP Server: A Tested Python and Node ExampleBuild a working MCP server in Python or Node, test it without a model, inspect it, then connect it to an AI app. Full code and the errors we hit.