Claude Code Subagents vs Agent Teams vs Parallel Sessions: One Task, Three Ways
We gave Claude Code the same three bug fixes three ways and recorded what each model cost, where the context lived, and where the merge conflict showed up.
Contents
Use subagents when one Claude Code session can hand off self-contained jobs and only needs the results back. Use an agent team when the workers have to talk to each other while they work; it costs the most and is still experimental. Use separate sessions in their own git worktrees when each piece should land as its own branch, and expect to resolve conflicts when you merge.

We gave Claude Code the same task all three ways on November 15, 2026: three independent bug fixes in a small Python repository, plus a project rule that every fix adds a line to a shared CHANGELOG.md. Every run used Claude Code 2.1.325 with Opus 5.5 at medium effort in auto mode on macOS, one run per method, so treat the numbers as a single sample rather than a benchmark. Anything we only read in Anthropic's documentation is marked as documented. Agentastic publishes this guide. Its section near the end was checked against Agentastic's documentation and source code, not run for this test.
The short answer#
| Subagents | Agent team | Sessions in worktrees | |
|---|---|---|---|
| What it is | Helpers inside one session | Several Claude Code instances led by one session | Separate claude processes you start |
| Who coordinates | The main session | The lead, by message and a shared task list | You |
| Workers talk to each other | They report to the caller; named ones can message each other | Yes, directly | No, unless you add cross-session messaging |
| Files | One shared working directory | One shared working directory | A worktree and branch each |
| Status | Built in | Experimental, off by default | Built in (claude -w) |
| Our run | 34.5 s, 523k tokens, one commit | 36.8 s, 768k tokens, one commit | About 11 s each, 627k tokens, three branches and one conflict |
Times are agent time from the session transcripts. Token totals include cached input, which is most of them; the results section breaks them down.
The test task#
The repository is a 100-line Python package with three modules and ten unit tests, five of them failing. TODO.md lists the fixes:
# Release 1.4 fixes
1. pricing: the total discount must never exceed 50%, and a code entered twice counts once. Tests: tests/test_pricing.py
2. shipping: charge for every started 500 g band, so 501 g is two bands. Tests: tests/test_shipping.py
3. tax: an unknown region must raise ValueError naming the region, instead of charging no tax. Tests: tests/test_tax.pyCLAUDE.md adds the catch. Each fix touches only its own module, but all three must write to the same file:
- Run the tests with `python3 -m unittest` from the repository root.
- Every fix adds exactly one line under `## Unreleased` in CHANGELOG.md, in the form `- <module>: <what changed>.`
- Don't edit files under tests/.That changelog rule is deliberate. It is the smallest version of what every parallel setup runs into sooner or later: independent pieces of work that still meet in one file.
Each method got a fresh clone of the same commit. Claude Code started with a clean environment, only the project's own settings, and cross-session messaging turned off, so no run could reach another session. The exact settings are in Reproduce the test. Token counts are the usage totals of every model request in each session's transcript, including the subagent and teammate transcripts that Claude Code saves beside it.
Way 1: subagents in one session#
The prompt:
Fix the three items in TODO.md, using one subagent per item, running in parallel. Follow CLAUDE.md. When all three are done, run python3 -m unittest and commit the work.
Before starting anything, the main session spotted the shared file: "Parallel agents all editing CHANGELOG.md would race, so each agent will fix only its own module and return its changelog line. I'll add the three lines myself." It launched three background subagents and told each one to change only its own module, stay out of tests/ and CHANGELOG.md, and not commit.
What we saw:
- The workers were Claude's built-in general-purpose subagent, started in the background, each at a lower effort level that the main session picked for them. Each finished in 7 to 8 seconds.
- Each subagent made three model requests and wrote about 26,500 tokens to the prompt cache. That is the cost of starting from a fresh context instead of the main conversation.
- The main session added the three changelog lines, ran all ten tests, and made one commit: 4 files, 11 lines added and 4 removed.
- The whole run took 34.5 seconds of agent time and asked for no permissions, because auto mode approved each step.
What Anthropic's subagents documentation adds (documented, not run):
- A subagent doesn't see the conversation history, the files the main session read, or skills it invoked. It gets its own system prompt, the brief Claude writes for it, the
CLAUDE.mdfiles, and a snapshot ofgit status. The read-only Explore and Plan subagents skipCLAUDE.md. - A fork is the exception: it inherits the whole conversation and shares the parent's prompt cache, so it costs less than a fresh subagent when the job needs the same context.
/subtask <task>starts one. - Subagents send their own requests, which count toward the same usage limits as the main conversation. Only their final result comes back into it.
- By default, up to 20 subagents run at once, and they can nest up to three levels below the main session.
- A subagent defined with
isolation: worktreeworks in its own temporary git worktree, which is removed automatically if it made no changes.
Way 2: an agent team#
Agent teams are off by default. We turned them on for this clone only, through the env block of the settings file passed with --settings:
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }The prompt:
Fix the three items in TODO.md, using an agent team with one teammate per item. Follow CLAUDE.md. When all three are done, run python3 -m unittest and commit the work.
The lead reached the same conclusion as the subagent run: "To avoid conflicting edits to CHANGELOG.md, each will send me its line and I'll add all three myself." It started three teammates, @pricing, @shipping and @tax, which appeared in the agent panel under the prompt.
What we saw:
- Each teammate fixed its module in 11 to 12.5 seconds and sent its result to the lead as a message. The lead reviewed the diff, added the three changelog lines, ran the full suite, and made one commit with the same four files.
- The run took 36.8 seconds of agent time and 768,000 tokens, 1.47 times the subagent run. Each teammate made four requests and wrote about 36,000 tokens to the prompt cache, against three requests and 26,500 tokens for a subagent.
- After the commit, each teammate went idle and its final report arrived a second time. The lead noted: "These messages are just the three teammates going idle and repeating the results they already sent."
- The shared task list stayed empty. The lead handed out the work in each teammate's spawn prompt instead of creating tasks.
- The team's config file,
~/.claude/teams/session-<id>/config.json, listed three in-process teammates on the same model, all in the lead's working directory. Nothing kept their files apart. The file was removed when the session ended; the task list folder stayed.
The agent panel looks the same for subagents and teammates, so the config file was how we confirmed this was a real team. Anthropic's docs say the same: Claude may use subagents even with teams enabled, so ask for a team explicitly and check.
When teammates write the shared file themselves#
In that run the lead kept the changelog for itself, so the shared file was never at risk. We ran the team again on a fresh clone and told each teammate to add its own line:
Fix the three items in TODO.md, using an agent team with one teammate per item. Each teammate adds its own CHANGELOG.md line, as CLAUDE.md asks. When all three are done, run python3 -m unittest and commit the work.
The three edits to CHANGELOG.md landed within three seconds of each other, and all three lines survived. The shipping teammate's edit was anchored on the pricing line, so it had read the file after pricing wrote it. The lead noticed ("Shipping's line is apparently in already"), added a blank line, ran the suite and committed. This run took 39.2 seconds and about 1,002,000 tokens.
One clean run doesn't make concurrent edits safe. Anthropic's agent teams documentation is direct about it: "Two teammates editing the same file leads to overwrites. Break the work so each teammate owns a different set of files."
What the agent teams documentation adds (documented, not run):
- Each teammate loads the project's
CLAUDE.md, MCP servers and skills, and gets the lead's spawn prompt. The lead's conversation history doesn't carry over. - Teammates start in the lead's permission mode, and their permission prompts appear in the lead's session. You can't give one teammate a different mode when it is spawned.
- Teams need an interactive session. In non-interactive mode (
claude -p), including Agent SDK sessions, Claude doesn't spawn teammates, and a subagent Claude names runs as an ordinary subagent. - While teams are enabled, a subagent that Claude names is launched as a teammate, so a team can form when you only asked for subagents. Set the variable back to
0to stop that. - Known limits:
/resumeand/rewinddon't restore in-process teammates, task status can lag, shutdown can be slow, a session leads one team at a time, and teams can't nest. - Anthropic suggests three to five teammates to start, with five or six tasks each.
Way 3: separate sessions in their own worktrees#
Here nothing coordinates the workers except you. We opened three terminals in the same clone and started one session per item, each in its own git worktree:
claude -w pricing
claude -w shipping
claude -w taxclaude -w <name> creates .claude/worktrees/<name> on a new branch called worktree-<name>, so all three started from the same commit with their own files. Each session got one item:
Fix item 1 (pricing) in TODO.md. Follow CLAUDE.md. When it is done, run python3 -m unittest tests.test_pricing and commit the work.
What we saw:
- The three sessions ran side by side and finished in about 11 seconds each. Each fixed its module, added its own changelog line, ran its own tests and committed on its own branch, with no permission prompts.
- Each one reported that the other modules' tests would still fail, which was true in its own worktree. No single session ever saw the whole fix.
- Together they used 627,000 tokens. Their cache writes were unusually low (38,800 in total), probably because the identical start of each session's prompt was already cached. We ran the methods back to back, so caching favours the later runs.
Merging is where the shared file shows up. From the main checkout:
git merge --no-edit worktree-pricing # fast-forward
git merge --no-edit worktree-shipping # CONFLICT (content): Merge conflict in CHANGELOG.mdgit diff showed the conflict. Each line has two marker columns, one per side: HEAD (pricing) first, then the shipping branch. A + in a column means that side doesn't have the line, so ++ marks the lines Git inserted:
@@@ -2,7 -2,7 +2,11 @@@
## Unreleased
++<<<<<<< HEAD
+- pricing: cap the total discount at 50% and count a repeated code once.
++=======
+ - shipping: charge for every started 500 g band, so 501 g is two bands.
++>>>>>>> worktree-shippingBoth branches added a line in the same place, so Git can't know which comes first. You can resolve it by hand and keep both lines. For files where every branch only appends lines, Git's built-in union merge driver keeps both sides on its own. We aborted, set the attribute for this clone only, and merged again:
git merge --abort
echo 'CHANGELOG.md merge=union' >> .git/info/attributes
git merge --no-edit worktree-shipping
git merge --no-edit worktree-tax
python3 -m unittest # Ran 10 tests ... OKBoth merges went through, the changelog kept all three lines, and all ten tests passed. Use union merges only for append-only files like this one. Git's gitattributes documentation warns that the added lines can end up in random order and asks you to check the result; in code, keeping both sides of a conflict usually breaks the build.
When you leave a worktree session, /exit asks whether to keep or remove the worktree and warns that removing it deletes the branch: "You have 1 commit on worktree-pricing. The branch will be deleted if you remove the worktree." Merge first, and removing it loses nothing.
What else is documented (not run): Claude Code can also start sessions in the background with claude --bg and manage them from agent view, a research preview. Those sessions move into their own worktree under .claude/worktrees/ before they edit anything. If you want your own sessions to pass notes to each other, cross-session messaging lets them send plain-text messages, never their history or files. We turned it off for this test so the sessions stayed independent.
The results side by side#
| Subagents | Agent team | Team, shared file | Worktree sessions | |
|---|---|---|---|---|
| Agent time | 34.5 s | 36.8 s | 39.2 s | About 11 s each, in parallel |
| Model requests | 16 | 20 | 26 | 15 |
| Total tokens | 523,486 | 767,886 | 1,002,459 | 626,706 |
| Cache writes | 125,087 | 154,963 | 130,066 | 38,815 |
| Output tokens | 4,464 | 6,195 | 7,151 | 2,754 |
| Merge work left to you | None, one commit | None, one commit | None, one commit | Three merges, one conflict |
Most of every total is cache reads: the same system prompt, tool definitions and files read again on each request. Output tokens and cache writes are where the methods differ.
What the numbers say, for a task this small:
- Subagents were the cheapest way to get one finished change. The main session kept the shared file to itself, and its workers started small.
- The team cost about 1.5 times as much and wasn't faster. Teammates are full sessions with bigger starting contexts, and each teammate's final report arrived twice. When teammates wrote the shared file themselves, the cost rose to almost twice the subagent run.
- Separate sessions finished first, but the integration was ours. The agents were done in about 11 seconds; the merges, the conflict and the final full test run were left to us.
This is one run per method on a three-line fix, so coordination overhead dominates. On real work, where each worker reads and edits far more, the ratios will move. Re-run the test on your own repository before you settle on a method.
Cost, context and merge conflicts#
Cost#
Every worker sends its own model requests. Anthropic's cost guide says a subagent's requests "still draw on your usage", and that agent teams "use approximately 7x more tokens than standard sessions when teammates run in plan mode." Its advice for teams is to use Sonnet for teammates, keep teams small because token use is roughly proportional to team size, and shut teammates down when their work is done, since each one keeps consuming tokens until it exits. On a Pro, Max, Ultra, Team or Enterprise plan, the /usage breakdown shows what share of your recent usage went to subagents.
Separate sessions each pay for a full system prompt and their own context. They pay nothing for coordination, because there isn't any: you do it.
Context#
- Subagents start almost empty and return a summary, so the main conversation grows only by their results. That makes them good for verbose side jobs. Anthropic's own example prompt is "Use a subagent to run the test suite and report only the failing tests with their error messages." The catch is that a subagent knows only what its brief says, and many detailed reports can still fill the main context.
- Teammates each have their own context window and load
CLAUDE.md, but not the lead's conversation. They can ask each other questions while they work, which is the reason to pay for a team. - Separate sessions share nothing. Whatever one learns, you have to carry to the others, or have them pass notes with cross-session messaging.
Merge conflicts and failure boundaries#
Subagents and teammates work in one directory. There is no merge step, but two workers can edit the same file and overwrite each other. In the subagent run and the first team run, Claude saw that risk on its own and kept the shared file for the coordinator. Worktree sessions can't overwrite each other, so conflicts surface at merge time, where Git shows them, instead of disappearing silently.
Failures stay inside different boundaries too (documented, not run). If a subagent hits an API error, it returns its partial output with a note, or is marked failed if it was running in the background. A teammate whose turn fails notifies the lead with the error. In-process teammates run inside the lead's session, and /resume and /rewind don't restore them, so a team doesn't outlive its lead. A separate session that fails affects only its own branch, and claude --continue in its worktree folder picks it up again.
When each one fits#
| Situation | Use |
|---|---|
| One change whose parts touch different files, delivered as one commit | Subagents |
| Verbose side jobs such as test runs, log digging or codebase searches | Subagents (Explore for read-only searches) |
| Parts that must agree while they work, like an API and its client | Agent team |
| Debugging with competing hypotheses, or a review from several angles | Agent team |
| Each part should become its own branch or pull request | Sessions in worktrees |
| Work that runs for hours, or tasks for different agents | Sessions in worktrees |
| Sequential steps, edits to the same file, many dependencies | One session, no parallelism |
Anthropic's guide to running agents in parallel asks whether the tasks touch the same files, and if they do, says to isolate the work with worktrees. Subagents and sessions you run yourself can each get a worktree, but "agent teams don't isolate teammates in worktrees", so give each teammate its own files.
Running the three methods in Agentastic#
Agentastic runs Claude Code itself, in a terminal pane or in its Chat view, so the three methods work the way they do in any terminal, with one exception below. What Agentastic adds is mostly around the third method. We checked this section against Agentastic's documentation and source code; we didn't run it for this test.
- Subagents. In Chat, Claude's subagents appear as a live tree beside the transcript: one row per subagent with its task, labeled when it needs input, fails or stops. Click a row to read that subagent's own conversation. Its output stays out of the main transcript.
- Agent teams. Agentastic's Chat view runs Claude Code in print mode with a streaming JSON protocol, and Anthropic's docs say teammates don't spawn in that mode. Start a team from
claudein an Agentastic terminal pane instead, where Claude Code's in-process display works as it does in any terminal. - Separate sessions. Agent Home starts each task in its own worktree, by default a folder beside the repository called
<repo>-worktrees/<task>, on its own branch. Pick several agents with an instance count each, for example Claude Code ×2 and Codex ×1, and every instance gets its own worktree, so different providers can take the same task. When a session finishes or needs you, its pane gets a colored ring, and Shift-Command-U jumps to the next agent waiting on you. Review each diff, leave line comments for the agent, then use Merge into current or open a pull request. - A coordinator that isn't a session. A Manager Agent is a long-running agent that doesn't edit code. It starts worker agents with the
devCLI, each one a full worktree agent with its own terminal or chat, and wakes up when a worker goes idle, is ready for review, waits for input or fails. It takes over the coordinating you did by hand in the third method, while each worker keeps its own branch.
For the day-to-day side of parallel sessions, see Parallel Coding Agents: A Workflow That Survives Review, Run Multiple Claude Code Agents in Parallel and Parallel Claude Code: 7 Problems Worktrees Do Not Solve.
Reproduce the test#
-
Make a small repository with three independent bugs in three files, failing tests for each, and the
TODO.mdandCLAUDE.mdshown above. Commit it, then clone it once per method so no run sees another's work. -
Save two settings files next to the clones. Both keep sessions from finding or messaging each other, and
team.jsonalso turns teams on. Teammates talk through theSendMessagetool, so onlysolo.json, used for the subagent and worktree runs, denies it.json{ "permissions": { "deny": ["SendMessage", "ListAgents"] }, "crossSessionInbound": "refuse" }json{ "permissions": { "deny": ["ListAgents"] }, "crossSessionInbound": "refuse", "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } } -
Start each run with a fixed model.
--setting-sources project,localleaves out your user settings, including hooks, so personal configuration can't change the result. We pinned Opus for the team and worktree runs; the subagent run used the account default, which was the same model.bashclaude --model opus --setting-sources project,local --settings ../solo.json # subagents claude --model opus --setting-sources project,local --settings ../team.json # agent team claude -w pricing --model opus --setting-sources project,local --settings ../solo.json -
Count tokens from the transcripts. Claude Code saves each session under
~/.claude/projects/<folder>/, with subagent and teammate transcripts in asubagents/folder beside it. Streamed messages repeat their usage, so count each message ID once. A worktree session has a folder of its own, so add up the three.pythonimport glob, json, os, sys # Usage: python3 count_tokens.py <folder name under ~/.claude/projects> folder = os.path.expanduser("~/.claude/projects/" + sys.argv[1]) keys = ("input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens", "output_tokens") totals, seen = dict.fromkeys(keys, 0), set() for path in glob.glob(folder + "/**/*.jsonl", recursive=True): for line in open(path): entry = json.loads(line) message = entry.get("message") or {} if entry.get("type") != "assistant" or "usage" not in message or message["id"] in seen: continue seen.add(message["id"]) for key in keys: totals[key] += message["usage"].get(key) or 0 print(totals, "total:", sum(totals.values())) -
Merge the worktree branches one at a time from the main checkout, and run the full test suite after the last merge.
Sources#
Anthropic's documentation, checked on November 15, 2026, with Claude Code 2.1.325:
- Create custom subagents
- Orchestrate teams of Claude Code sessions
- Run agents in parallel
- Manage costs effectively
- Run parallel sessions with worktrees
- Message your other Claude Code sessions
- Manage multiple agents with agent view
Also: Git's gitattributes reference for the union merge driver, and Agentastic's Chat, Manager Agents and multi-agent guide documentation for the Agentastic section.
Frequently asked questions#
What is the difference between Claude Code subagents and agent teams?#
Subagents are helpers inside one session: each starts with a fresh context, does one job, and returns its result to the session that started it. An agent team is several full Claude Code instances led by one session, whose teammates message each other directly and share a task list. Agent teams are experimental and off by default.
How do I turn on Claude Code agent teams?#
Set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS to 1, in your shell or in the env block of settings.json, then ask Claude to create a team in an interactive session. Teams don't form in non-interactive mode (claude -p) or through the Agent SDK.
Do agent teams use more tokens than subagents?#
Yes, because every teammate is a separate Claude Code instance with its own context. In our three-fix test the team used about 768,000 tokens and subagents about 523,000. Anthropic's cost guide says teams use approximately 7x more tokens than standard sessions when teammates run in plan mode.
Can two Claude Code agents edit the same file at the same time?#
Subagents and teammates share one working directory, so nothing stops them, and Anthropic warns that two teammates editing the same file leads to overwrites. Give each agent its own files, or give each session its own git worktree and resolve conflicts when you merge.
How do I run parallel Claude Code sessions safely?#
Start each one in its own worktree with claude -w
Which should I use for a larger feature?#
If the parts touch different files and you want them back as one change, subagents cost the least. Use an agent team when the parts must agree on something while they work, such as an API and its client. Use separate worktree sessions when each part should become its own branch or pull request.
Do agent teams work in Claude Code GUI apps?#
Only where Claude runs as an interactive session. Apps that drive Claude through print mode or the Agent SDK get ordinary subagents instead of teammates. Agentastic's Chat view uses print mode, so start a team from claude in an Agentastic terminal pane.