All resources
Guide/8 min read

Subagents in Claude Code: what they are, and what they cost in a real run

Published

Summary

What subagents are in Claude Code and Codex, and 28 measured runs: on small tasks subagents cost 2 to 3 times as much and saved no time. When they do help.

A subagent is a helper that a coding agent starts in the middle of a task. It gets its own context window and a short brief, does one piece of the work, and hands back a summary. Claude Code and Codex both have them.

The usual pitch is that subagents make an agent faster and keep its context clean. We wanted to know what that looks like on real tasks, so we ran the same jobs with and without subagents and recorded the time, tokens and cost of every run: 16 Claude Code runs on two small Flask tasks, then 12 runs of a bigger, read-heavy task in Replicas workspaces, split between Claude Code and Codex.

The results depended on the task. On the two small tasks, subagents made each run cost two to three times as much and didn't save any time, and Claude never chose to use them on its own. On the bigger task, they cut Claude's main context by about a third and finished sooner, for about a fifth more money.

This guide explains what subagents are, what we measured and why it came out that way, what went wrong, and how subagents show up in a Replicas chat.

Bar chart of time and cost per run. Fixing four planted bugs: 56 seconds and $0.23 with subagents off, 57 seconds and $0.24 when Claude could choose, 74 seconds and $0.72 when told to use one subagent per part. Answering four questions: 99 seconds and $0.58 off, 91 seconds and $0.55 when Claude could choose, 104 seconds and $1.37 with one subagent per question

What a subagent is

Anthropic's subagents docs describe a subagent as an assistant that "runs in its own context window with a custom system prompt, specific tool access, and independent permissions." The main conversation writes it a delegation message, the subagent works through the task with its own tool calls, and only its final report comes back. The idea is that search results, logs and file contents stay in the subagent's context instead of filling up the main one.

A few details from the same docs matter for what we saw:

  • It starts from scratch. A subagent doesn't see your conversation history or the files the main agent already read. It gets its own system prompt, the delegation message, your CLAUDE.md files and a git status snapshot. The built-in Explore and Plan subagents skip the CLAUDE.md files and git status.
  • It runs in the background by default. The main agent keeps going, and each subagent's result "reach[es] Claude as a completion notification in a later turn."
  • It costs its own tokens. Each subagent "sends its own requests, which count toward the same usage limits as your main conversation," and Anthropic's cost guide says the same.
  • It can nest. A subagent can start its own subagents, up to three layers below the main conversation.

Claude Code ships three subagents you'll see most: Explore (read-only, for searching a codebase), Plan (read-only research in plan mode) and general-purpose (every tool, for work that reads and edits). You can write your own as Markdown files in .claude/agents/, with their own prompt, tools and model.

Claude Code subagents vs Codex subagents

This table is from each vendor's docs. Our own Codex runs are in the bigger task below.

Claude CodeCodex
On by defaultYes. Claude delegates when a task matches a subagent's descriptionYes. Codex starts them when you ask, or when project or skill instructions say to
Built-in subagentsExplore, Plan, general-purposedefault, worker, explorer
Custom subagentsMarkdown files in .claude/agents/ or ~/.claude/agents/Agent files, plus [agents] settings in config.toml
ModelThe parent's model unless the subagent or the call sets oneThe parent's model and reasoning effort unless you set them
What the docs say about costEach subagent's requests count toward your usageSubagent workflows "consume more tokens than comparable single-agent runs"

Sources: Claude Code subagents, Codex subagents.

Subagents vs agent teams vs parallel sessions

These get mixed up because all three involve more than one agent.

What it isWho talks to whom
SubagentsHelpers inside one sessionEach one reports only to the agent that started it
Agent teamsSeveral Claude Code sessions that one lead session spawns and supervises. Off by defaultTeammates each have their own context window and coordinate through the lead
Parallel sessionsSeparate agents on separate tasks, each in its own checkout or machineThey don't talk to each other. You review each result

Subagents are for splitting up one task. Parallel sessions are for running several tasks at once. Our guide to orchestrating coding agents covers all of these in more depth.

What we ran

We used a copy of Flask at commit 49943b5 and gave Claude Code two tasks:

  • Fix four planted bugs. We changed one line in each of four files (config, JSON tags, blueprints, sessions), which made 13 of Flask's 491 tests fail across four test files. The prompt asked Claude to find the root cause of every failure and fix the code without editing tests.
  • Answer four questions about Flask, with line numbers. How a KeyError in a view becomes a 500 response, how the session cookie is signed, how flask run finds an app, and how url_for(".index") resolves inside a blueprint. The answers need reading Flask, Werkzeug, itsdangerous and Click. No files change.

Each task ran in three ways:

  • Subagents off: the plain prompt, with Claude Code's Agent tool removed (--disallowedTools Agent). 3 runs.
  • Claude's choice: the plain prompt with subagents available. 2 runs.
  • One subagent per part: the plain prompt plus one extra paragraph. For the bugs: "Use subagents: first see which areas are failing, then start one subagent per area, in parallel, and have each one find, fix and test its own area." For the questions: "Use subagents: start one subagent per question, in parallel, and combine their answers." 3 runs.

Every Flask run used Claude Code 2.1.330 on Claude Opus 5.5 with its default settings, in headless mode (claude -p), inside one Replicas workspace. Each run got a fresh copy of the repository. The time is wall-clock time from our script. Cost and tokens come from the summary Claude Code prints at the end of a headless run, which estimates cost at list prices. The phase timings below come from the timestamps in Claude Code's session transcripts.

Results on the two Flask tasks

Subagents offClaude's choiceOne subagent per part
Fix four bugs: time56 s (49–58)57 s (53–61)74 s (68–78)
Cost$0.23 ($0.20–0.23)$0.24 ($0.20–0.27)$0.72 ($0.70–0.73)
Input tokens processed223k (162k–223k)256k (174k–339k)588k (586k–646k)
Output tokens1.7k1.9k6.7k
Subagents started004 in every run
Answer four questions: time99 s (83–109)91 s (85–98)104 s (96–117)
Cost$0.58 ($0.51–0.71)$0.55 ($0.52–0.57)$1.37 ($1.33–1.46)
Input tokens processed598k (440k–807k)522k (437k–607k)807k (708k–892k)
Output tokens8.7k7.6k23.1k
Subagents started004 Explore subagents in every run

Medians, with the range in brackets. Input tokens include cached tokens.

Every run got the right result. All eight bug-fix runs made the same four one-line fixes and ended with 491 tests passing. All eight question runs answered all four questions, and the line numbers we spot-checked were right. So subagents didn't change the quality of the work here. They changed the bill: about 3.1 times the cost on the bug fix and 2.4 times on the questions.

When subagents were available but not requested, Claude didn't use them in any of the four runs, even for four independent questions. Those runs cost the same as the runs with subagents turned off.

Where the time went

Four subagents working at once should finish sooner than one agent doing four things in a row. The transcripts show why they didn't.

Timeline of one run of each. Fixing bugs without subagents took 52 seconds. With subagents, the main agent spent 37 seconds reading failures and writing four subagent prompts, the subagents ran between 30 and 54 seconds, and the run ended at 63 seconds. Answering questions without subagents took 94 seconds. With subagents, the main agent wrote prompts until 22 seconds, the subagents ran from 10 to 62 seconds, and combining their answers took until 93 seconds

The split comes first, and it's slow. On the bug fix, the main agent ran the tests, read the failures and grouped them before it started any subagent: 27 to 32 seconds in, across the three runs. It then wrote a separate brief for each subagent, about 500 to 700 characters each, one after another, so the last subagent started 6 to 7 seconds after the first. By then, the agent working alone was about two thirds of the way through the whole job.

The parallel part was short. The four bug-fix subagents each took 9 to 31 seconds. That part did run side by side. But each one started fresh, so each re-ran its own tests and re-read code the main agent had already looked at.

Combining the answers took half a minute. On the questions, the last subagent finished 62 to 79 seconds in, and the main agent then spent another 31 to 35 seconds checking a few line numbers and writing the final answer from four long reports. The bug fix needed less: about 9 seconds to run the full suite once more and summarize.

The saving from running in parallel was real but smaller than the cost of splitting the work up and putting it back together. On tasks this size, that overhead decides the result.

Where the money went

Three things made the subagent runs more expensive, and all three are visible in Claude Code's token counts.

Every subagent pays to start. Each subagent's first request was already about 17,000 tokens (Explore) or 19,000 tokens (general-purpose) before it read a single file: its own system prompt, its tool definitions and the brief. At least 12,000 of those were new to the prompt cache every time, and writing to the cache costs more than reading from it. On the bug fix, the runs with subagents wrote 83,000 to 86,000 tokens to the cache, against 17,000 to 19,000 for a single agent.

The work gets written twice. The question subagents each returned a report of 5,300 to 8,400 characters, and the main agent then wrote its own answer from them. Output tokens went from 8,700 to 23,100. Output is the most expensive kind of token.

Some work gets done more than once. The main agent ran the failing tests to decide how to split the job, then each subagent ran its own tests again, then the main agent ran the full suite at the end. Counting every agent, the bug-fix runs with subagents called pytest 14 to 17 times. A single agent called it 3 or 4 times.

Anthropic's docs point out that a fork, a subagent that inherits the whole conversation, can reuse the parent's prompt cache and so costs less to start. We didn't test forks.

What it saved

The case for subagents is that they keep the main context small. They did, a little. On the questions, the main conversation peaked at a median of 45,500 tokens with subagents and 47,200 without. On the bug fix it peaked higher with subagents, 34,400 against 30,600, because the main agent read the failures itself before delegating and then received four reports.

None of these runs came close to filling a context window. A few thousand tokens of saved context didn't buy anything here, and it cost two to three times as much to get.

A bigger, read-heavy task

Flask's planted bugs were small on purpose. To see whether a bigger job changes the picture, another agent session on our team ran a task with more reading in it, the same day, in real Replicas workspaces on a development build of Replicas. The repository was a fork of the FastAPI full-stack template, with a Python backend, a React frontend and GitHub Actions CI. The prompt:

One version added "Use three subagents in parallel, one per area. Have each one return a short summary with file paths, then write the file yourself from their summaries." The other added "Do all the reading yourself. Don't use subagents." Each ran three times in Claude Code on Opus 5.5 and three times in Codex on GPT-6.1 Sol, with Replicas' default settings. We re-checked the Claude numbers below against the raw chat histories.

Claude Code with subagentsClaude Code withoutCodex with subagentsCodex without
Time92 s (91–108)128 s (101–146)71 s (65–72)60 s (55–63)
Cost$0.82 ($0.77–0.86)$0.67 ($0.67–0.80)Not measuredNot measured
Main conversation at the end50.5k tokens (47k–51k)73.5k tokens (71k–78k)35.5k tokens (35k–36k)51.1k tokens (45k–55k)
Subagents started3 Explore, every run03, every run0

Medians, with the range in brackets. Every run wrote the file. Every file the docs cited exists in the repository, apart from openapi.json, which the docs correctly describe as generated, and no cited line number was past the end of its file.

This time Claude came out ahead with subagents. Working alone, Claude made 16 to 18 tool calls and read every file into its own context. With subagents, it made 8 to 10, and the three Explore subagents took 17 to 23 seconds each. The main conversation ended about a third smaller, and the median run finished 36 seconds sooner, though the slowest run with subagents (108 s) was slower than the fastest run without (101 s). It still cost more, about 22% at the median, but far less than the 2.4 to 3.1 times on Flask.

The prompt asked each subagent for "a short summary with file paths," and output tokens barely moved: 14,300 with subagents against 13,500 without, at the median. On the Flask questions, where the subagents wrote reports of 5,000 to 8,000 characters, output nearly tripled.

Codex was slower with subagents. Its main thread didn't wait for them: it ran about 10 of its own cat and rg commands on the same files while its three subagents read them. In the one round where we pulled Codex's token counts from its session logs, the run with subagents used about 2.6 times the input tokens of the run without, once the subagents' own threads are counted (743,000 against 287,000). Its main thread still ended a third smaller, as Claude's did.

What went wrong

Nothing failed outright, but three things happened that you'd want to know about before using subagents on a bigger change.

The split followed the test files, not the causes. In every bug-fix run, the main agent split the work by failing test file. One of the session tests, test_extended_flashing, was actually broken by the JSON tag bug, which belonged to another subagent. So the sessions subagent spent its time proving the failure wasn't its own while the JSON tag subagent fixed the real cause. That subagent was the slowest in two of the three runs, at 29 and 31 seconds against 10 to 17 for the others. When we repeated the task in a Replicas workspace, the main agent grouped sessions and JSON tags into one subagent from the start, which avoided this.

A subagent's line numbers were wrong. On the bigger task, Claude's backend subagent ran cat -n core/security.py api/deps.py. cat -n numbers the lines of both files as one stream, so every line it reported for deps.py was 36 too high, the length of security.py: it put get_current_user at lines 66 to 82 instead of 30 to 46. The main agent checked the summary against the source, noticed, re-read the file and fixed the numbers. It also dropped the line numbers it hadn't checked:

Claude's final reply in a Replicas chat: three subagents researched the areas in parallel, and it spot-checked their summaries, found the backend agent's line numbers for deps.py were wrong, replaced them, and cited file paths and function names elsewhere because it didn't check every line number

A subagent's report is a summary from an agent you didn't watch work. Here the main agent caught the mistake because it checked, which is worth asking for when the details matter.

Subagents shared one checkout. In one run, the sessions subagent ran git stash to test the original code, then git stash pop. In a checkout that four subagents were editing at once, that briefly removed the other subagents' uncommitted changes too. The others had already finished their own testing, so nothing broke, but on a longer task it could have. In another run, the same subagent copied the repository to /tmp and tested there instead, which was safer. Claude Code can give a subagent its own copy with isolation: worktree in its definition; our runs used the built-in subagents, which don't set it.

How subagents show up in Replicas

Replicas runs Claude Code and other coding agents in cloud workspaces, and its chat shows each native Claude Code subagent as it runs. We ran both Flask tasks again on a development build of Replicas, with the "one subagent per part" prompt.

Each subagent gets a row in the chat with its type, its description and whether it's still working or finished:

Replicas chat showing four Explore subagents, one per question. Q2 and Q3 have finished while Q1 and Q4 are still thinking, and the main agent says Q2 is back and it's waiting on the other three

Because subagents run in the background, the main agent ends its turn after starting them and gets woken up each time one finishes. That's why the chat shows short turns like "Q2 is back. Waiting on the other three." Our headless runs did the same: one bug-fix run produced five separate replies, one after each subagent and a final one.

Clicking a subagent opens its transcript in the sidebar: the brief the main agent wrote for it, every command it ran and the report it sent back. The Subagents tab lists every subagent the chat has started (workspace docs).

Replicas workspace with a Claude Code subagent's transcript open in the sidebar. It shows the brief for fixing the blueprint test failures, and its report that a missing slash between the parent and child URL prefixes caused all the blueprint failures

These are Claude Code's own subagents inside one workspace. Replicas also has agents that work at a larger scale: a Manager starts separate workspaces for separate tasks, each with its own agent, machine and pull request. That's the parallel-sessions row in the table above, not a subagent, and we didn't measure it here.

When subagents are worth it

From these runs and Anthropic's own guidance:

  • Use them for big, separate pieces of reading. On the full-stack docs task, three independent areas with a lot of files each, subagents kept a third of the reading out of Claude's main context and finished sooner for about 22% more.
  • Skip them for small, connected tasks. Anthropic's docs say to stay in the main conversation when "latency matters," because a subagent "starts fresh and may need time to gather context." Our bug fix and questions were both small enough that a single agent finished first and cheaper.
  • Use them when the output is big and you only need the conclusion. Long test logs, documentation, or a search across a large codebase are the cases Anthropic recommends. The saving grows with how much the subagent reads and how little it reports back. Ours read a few files each and wrote long reports, the worst ratio.
  • Ask for short reports. Four reports of 5,000 to 8,000 characters each roughly tripled the output tokens on the Flask questions. On the docs task, where the prompt asked for "a short summary with file paths," output barely changed.
  • Check what comes back. A subagent's line numbers were off by 36 lines in one run. Ask the main agent to verify details it will rely on.
  • Split by cause, not by symptom. If the parts aren't really independent, subagents duplicate work or step on each other. Give parallel editors their own worktree.
  • Put cheaper models on simple subagents. Every subagent in our runs used Opus 5.5 because it inherits the main model. Anthropic's cost guide suggests Haiku for simple subagent tasks. We didn't test that.

Limits of this test

This is a small, controlled test, not a benchmark. Read the numbers with that in mind:

  • Three tasks, two repositories. The Flask tasks were small, and the docs task was medium-sized. None came close to filling a context window, and we didn't test longer jobs where that happens.
  • Two or three runs per setup. The ranges are wide enough on the questions task that the time difference there is within noise. The cost difference isn't: every subagent run cost more than every run without.
  • Runs ran at the same time. The 16 Flask runs ran together on one machine, and the docs task ran in rounds of four workspaces, so times include some contention. Every setup in a test ran under the same conditions.
  • Costs are Claude Code's list-price estimates, including prompt caching. A Claude subscription counts usage differently, but the token counts still apply.
  • Different settings between tests. The Flask runs used Claude Code's headless mode with its default settings. The docs task ran through the Replicas chat at Replicas' default High effort. Compare within a test, not across them. In an interactive session, Claude might also choose subagents more often than in our four headless runs.
  • An earlier batch of eight bug-fix runs, which we discarded because our script failed to record wall-clock time, showed the same cost gap: $0.64 to $0.70 with subagents and $0.22 to $0.28 without.
  • Codex on one task only. We ran Codex on the docs task, and have its token counts for one round, so we don't give a Codex cost. We didn't test other agents' subagents.

AI agents in Replicas workspaces ran these tests on November 22, 2026, and a person on our team reviewed this guide before it was published. Replicas is our product.

If you want to run Claude Code with or without subagents in the cloud and watch each one in the chat, try Replicas with $100 of free usage. For running several agents on separate tasks instead, see how to orchestrate coding agents and Claude Code in the cloud.

FAQ

Frequently asked questions