Claude Code subagents: what they are and what they cost

A subagent is a helper that Claude Code starts to do one piece of a job, such as searching a codebase, and report back. Each one is its own session with its own context, so they are useful and they are often where most of the tokens go.

What a subagent is

The main session hands a task to a helper. The helper works separately, with its own instructions and tools, and returns a summary. This keeps the main conversation short, because all the reading the helper did never enters it. Several helpers can run at once.

Why they add up

When the main session hands work to a subagent, the helper starts with its own instructions and tool list, does its own reading and running, and reports back a summary. The main session only sees the summary. The tokens the helper spent getting there are still spent.

What it looked like in practice

On the author's Mac, over one week, the share of turns made by subagents ranged from 0 to 61 percent depending on the day. On the heaviest day, 3,402 turns were recorded and 61 percent of them were subagent turns.

The figures on this page come from real session logs on the author's Mac, read with Cost Doctor. Your numbers will differ; the pattern usually does not.

Why you may not be seeing them

Subagent activity is written to a separate place: each session has a subagents folder beside its own log, with one file per helper. A tool or script that only reads the top-level session files misses all of it. An early count on the same machine did exactly that and reported about a third of the real total.

How to keep them in check

• Use a subagent when the work is independent and wide, such as searching many files. Do not use one for a lookup you could do in one step.
• Give each helper a narrow job. A vague brief makes the helper read widely before it starts.
• Cap how many run at once. Ten helpers in parallel spend ten contexts in the same minute.
• Watch the share. If most of a session's tokens are from helpers, change how the work is being split, not the session.

Cost Doctor includes the subagent logs in every total and shows, per session, what share of its tokens went to subagents. It flags a session when that share is high and the amount is large.