...your CLAUDE.md
on every turn
again, and again.
and again...
Every custom subagent you spin up in Claude Code gets a copy of your CLAUDE.md before it does any work. Then it carries that copy along on every request until it finishes.
If you've got a big CLAUDE.md, every subagent starts with a pile of tokens before it's even looked at your code.
I went through the 722 subagent logs on my machine (September 26 to November 2). My code reviewer started at a median of 80,111 tokens on its first request. Claude Code's built-in Explore agent started at 7,578.
Same machine, mostly the same repos. One gets the house rules. The other doesn't.
Why the gap
Anthropic's subagent docs are pretty clear about this: "Explore and Plan start without your CLAUDE.md files and the git status snapshot to keep research fast and inexpensive." Every other subagent, built-in or custom, loads both unless you tell it otherwise.
I figured the tools might account for some of the difference. My reviewer only has four (tools: Read, Grep, Glob, Bash), so that wasn't much of an explanation.
Then I looked at my CLAUDE.md.
The one in the jCodeMunch repo is 1,064 lines. That's 36,931 tokens using tiktoken's cl100k count (Claude's tokenizer will give you a somewhat different number).
Apparently I need to start taking my own advice.
Each subagent runs its own conversation, and every request carries the conversation's context along with it. My reviewers took a median of 17 requests.
17 times 36,931 comes to about 628,000 tokens per review. Just for the house rules. The agent hasn't opened a file yet.
Now, most of those repeated tokens bill at the cached rate. That helps, and I went through the math on that last week. But cached doesn't mean free, and on a subscription it all comes out of the same usage limits.
Somebody on r/ClaudeCode described their starting context as "So ~125k before any work happens". Another reported: "It spun up 20+ agents and burned my entire 5 hour window in 15 mins".
Multiply that starting context by the number of agents, and then by the requests each one makes, and the numbers start making a little more sense.
Not necessarily the kind of sense you wanted, but sense nonetheless.
Measure your own
Claude Code keeps subagent transcripts alongside the parent session, in ~/.claude/projects/<project>/<session>/subagents/.
Each subagent has a little .meta.json file naming its agentType, and the .jsonl transcript has the API usage block on each assistant entry, same as the main session.
One caution, same as last time: Anthropic doesn't document this log format. It's fine for poking around your own sessions, but I wouldn't build anything important on it staying the same.
import glob, json, os from collections import defaultdict from statistics import median root = os.path.expanduser("~/.claude/projects") first, turns, sent = defaultdict(list), defaultdict(list), defaultdict(int) for log in glob.glob(os.path.join(root, "*", "*", "subagents", "*.jsonl")): try: kind = json.load(open(log[:-6] + ".meta.json", encoding="utf-8")).get("agentType", "?") except (OSError, ValueError): kind = "?" sizes, seen = [], set() for line in open(log, encoding="utf-8"): try: m = json.loads(line).get("message") or {} except ValueError: continue u = m.get("usage") if isinstance(m, dict) else None if u and m.get("id") not in seen: seen.add(m.get("id")) sizes.append(u.get("input_tokens", 0) + u.get("cache_read_input_tokens", 0) + u.get("cache_creation_input_tokens", 0)) if sizes: first[kind].append(sizes[0]) turns[kind].append(len(sizes)) sent[kind] += sum(sizes) print(f"{'agent type':20}{'runs':>6}{'first request':>15}{'requests':>10}{'tokens sent':>16}") for kind in sorted(first, key=lambda k: -sent[k]): print(f"{kind[:19]:20}{len(first[kind]):>6}{median(first[kind]):>15,.0f}" f"{median(turns[kind]):>10.0f}{sent[kind]:>16,}") print("(first request and requests are medians per run)") python subagentfloor.py Here's mine (Claude Code 2.1.316, a few test agents trimmed off the bottom):
agent type runs first request requests tokens sent reviewer 406 80,111 17 1,017,763,755 general-purpose 67 66,703 17 211,755,063 Explore 202 7,578 3 16,942,168 spokesperson 22 77,372 2 6,823,506 claude-code-guide 6 112,665 4 3,765,695 web-fetch 10 3,893 4 1,214,448 (first request and requests are medians per run) The column to look at first is "first request".
That's the agent's starting floor. System prompt, CLAUDE.md, git status snapshot, tool definitions, and whatever instructions the main session handed it.
Every request after that carries the same starting baggage, plus whatever the agent has picked up while working.
You can also count the tokens in your own CLAUDE.md:
python -c "import tiktoken; print(len(tiktoken.get_encoding('cl100k_base').encode(open('CLAUDE.md', encoding='utf-8').read())))" The thing I expected to matter more
I went into this expecting file re-reads to be the big problem.
You see people say it all the time: "the gap is re-reads, not work."
Fair enough. I figured I'd measure that too, in my three busiest sessions (78, 127 and 225 subagents).
Files another agent had already read accounted for 9% to 13% of all the file content read.
File contents carried into later turns came to 2% to 6% of what the subagents sent.
The starting context, re-sent every turn, was 52% to 69%.
Well, that wasn't what I expected.
Now, my agents don't spend much time crawling through the repo. I've got some tooling that changes how they find code, which I'll get to below. If your agents spend their days opening files, your numbers could look considerably different.
Still, the starting floor might be worth measuring before you go chasing re-reads. It's sitting there on every request, whether the agent does anything useful or not. And it's relatively easy to fix.
Lowering the floor
First up might be omitClaudeMd: true.
Put that in the frontmatter of an agent that doesn't need your project rules. Per Anthropic's docs, it starts the subagent "without the user, project, and local CLAUDE.md files in its initial context."
A test runner probably doesn't need to know how you format commit messages. Neither does an agent summarizing logs.
A code reviewer that's supposed to enforce those conventions? Different story. Leave the rules in place for that one, or at least give it the parts it actually needs.
It might also be worth a look at what's piled up in CLAUDE.md itself. Mine is obviously overdue for some housekeeping. If a section only matters to one kind of agent, it can live in that agent's own file, and nobody else has to carry it.
For looking around the repo, Claude Code already has Explore. It skips CLAUDE.md and runs read-only.
A decent brief helps too. The main session already knows quite a bit about the repo. If it knows which files and functions need attention, have it pass those names along instead of making the new agent rediscover them.
And if the job doesn't need a big model, Anthropic's costs page suggests model: haiku in the agent's config.
None of this needs another tool. Just a little attention to what you're making each agent carry around.
Where jCodeMunch fits
Once you've dealt with the starting context, there's still the matter of how a cold agent finds its way around the code.
Normally it searches, opens files, finds the function it wanted, and keeps all that file content in its conversation for the rest of the run.
That's the part I built jCodeMunch for.
A subagent only gets the tools allowed in its agent file. Add mcp__jcodemunch__* to the tools: line and it can ask for a function by name instead of opening the entire file. On our benchmark that's 94.5% fewer tokens per lookup on average than grep-and-read (15 lookups across express, fastapi and gin; method here).
Run jcodemunch-mcp init --guidance and each spawned subagent also gets a condensed briefing about the repo, so it doesn't start completely cold.
And here's the embarrassing part.
Remember my reviewer? The one that starts at 80,111 tokens and spends 17 requests doing its job?
I checked its tools: line.
No jCodeMunch.
Guess what I'm fixing tonight...
FAQ
Does a subagent see my main conversation?
Not a regular one. It starts with its own context: its system prompt, CLAUDE.md (unless omitted), the git status snapshot, its tools and the brief. A fork is the exception; it inherits the conversation so far.
Does omitClaudeMd drop everything?
It drops the user, project and local CLAUDE.md files. Managed policy files still load, and the git status snapshot is separate.
Why is my first request different from yours?
It depends on your CLAUDE.md, your repo's git status, the tools the agent gets and how long the brief is. That's why the script is there.
Aren't cached tokens nearly free?
Cheaper per token, yes. They still add up across 17 requests and 20 agents, and they still count.
