tokenise by Rosvetic
Assistants Tips

Every subagent re-reads your CLAUDE.md. Here's when to switch that off

A Claude Code subagent loads your whole CLAUDE.md hierarchy by default. The omitClaudeMd field skips it, and a ten-minute test shows what you save and what you lose.

8 min read

A stack of cream paper sheets with a small cut-out door, beside one thick pink sheet lifted out of the stack

Every time Claude Code hands work to a subagent, the subagent starts by reading your CLAUDE.md. All of it: the user file, the project file, CLAUDE.local.md, any AGENTS.md loaded as project instructions. The sub-agents docs list it as part of a subagent’s initial context, next to its own prompt, the task message and a git status snapshot. A 300-line CLAUDE.md you wrote for the main session gets paid for again in every worker it spawns.

Often that’s what you want. Sometimes it’s pure overhead, and one frontmatter field turns it off. Here’s what the field does, a test that shows it working, and a rule for deciding which subagents should have it.

The field

omitClaudeMd is a boolean in a subagent’s frontmatter. It needs Claude Code 2.1.271 or later. Set it to true and the subagent launches without the user, project and local CLAUDE.md files. Managed policy files still load.

---
name: repo-auditor
description: Audits a large repository and reports what it finds
omitClaudeMd: true
---

It also works in --agents JSON. Two limits from the docs: it’s ignored when the agent runs as your main session agent (via --agent or the agent setting), and the built-in Explore and Plan agents already skip CLAUDE.md, so there’s nothing to switch off on them.

Your main conversation is unaffected. It still has the full CLAUDE.md when it reads the subagent’s result, which is the reason most rules don’t need to reach the worker at all.

A test you can run in two minutes

Don’t take the docs’ word for it. Put a codeword in a CLAUDE.md and write two near-identical subagents, one with the flag and one without. Both are told to report the codeword from their instructions and not to read any files.

---
name: echo-a
description: Reports which project instructions it can see. Use when asked to run echo-a.
tools: Read
model: haiku
---
Report, in one sentence, the project codeword from your instructions, or say "none visible" if you have no codeword. Do not read any files.

The second file, echo-b, is identical except for one extra frontmatter line, omitClaudeMd: true. The project’s CLAUDE.md contains The project codeword is PELICAN-42. Then run each one headlessly (paths in the output below are shortened to <repo>):

claude -p "Run the echo-a subagent and print exactly what it answered." --permission-mode acceptEdits

On Claude Code 2.1.296, echo-a answered:

The echo-a subagent answered:

> The project instructions I can see, from `<repo>/CLAUDE.md`, give the project codeword as PELICAN-42, and they say to mention it whenever conventions come up.

And echo-b:

The echo-b subagent answered:

> I can't see any project instructions. No CLAUDE.md or other project-specific instruction file is in my context, and I haven't read any files. The only guidance I have is general: the environment details (working directory `<repo>`, scratchpad usage, and proxy notes) and git attribution rules for commits and PRs. Codeword: none visible.

The flag does what it says. Note the last detail in the second answer: the subagent still gets environment details and the commit-attribution rules the harness appends. omitClaudeMd removes your instruction files, not everything.

What it saves

To see the size of the saving, the CLAUDE.md in that test was padded to 3,607 words with 180 near-identical rule lines. That’s deliberately oversized (Anthropic’s own advice is to keep the file short, as covered in how to prune your CLAUDE.md ), so treat the result as a ceiling. Running with --output-format json reports usage per model, and the Haiku subagent is the only Haiku call in the session:

echo-a (CLAUDE.md loaded):   input 1,186   cache creation 8,602   cache read 1,388
echo-b (omitClaudeMd: true): input 1,186   cache creation     0   cache read 2,646

That’s about 11,200 input tokens for the subagent that read the file against about 3,800 for the one that didn’t, a gap of roughly 7,300 tokens. This is one run of each, and the cache-creation and cache-read split depends on what was already cached, so don’t read the exact figures as a benchmark. The direction is the point: the subagent that skipped CLAUDE.md started with a much smaller context.

Per call that’s small money. It adds up when a workflow fans out a dozen workers, or when a subagent runs many turns and carries those tokens on every one. The Haiku 5.5 subagent post covers the other cost lever, the model, and effort per sub-agent covers the third. Context is the one nobody thinks to tune.

Which subagents should have it

The docs give the criterion in one line: use it for subagents that take everything they need from the delegation prompt. Translate that into a test. Ask whether the worker could do its job if it were handed a contractor’s brief and nothing else.

Good candidates:

  • A log or output summariser. It gets a blob of text and returns three bullets. Your naming conventions are irrelevant to it.
  • A dependency or licence auditor that reads manifests and reports versions.
  • A read-only search worker that finds callers of a function and lists file and line.
  • A formatter or converter working to an explicit spec in the prompt.

Poor candidates:

  • Anything that writes code in your repo. It needs your conventions: test framework, error handling, where files go. Strip CLAUDE.md and it will cheerfully produce plausible code in the wrong style.
  • A reviewer that checks the diff against house rules. If the rules live in CLAUDE.md and the reviewer can’t see them, it reviews against generic taste. The fresh-context reviewer from the diff reviewer how-to is a case where fresh eyes on the diff are the point, but the checklist still has to come from somewhere. Put it in the agent’s own prompt if you drop CLAUDE.md.
  • Anything with a hard prohibition in CLAUDE.md (“never touch migrations/”). More on that next.

The trap: rules that quietly stop applying

CLAUDE.md is advisory context, and so is its absence. A rule you wrote there protects you from the subagent only while the subagent can see it. With omitClaudeMd the worker no longer knows about your vendor/ directory, your generated-code folder or the rule against editing lockfiles.

Two defences, both from the docs and common sense. First, restate anything that must reach the subagent in the prompt you give Claude when delegating; the docs’ own example is “ignore the vendor/ directory”. Second, don’t rely on prose for anything that has to hold. A tool allowlist in the subagent’s tools field and a PreToolUse hook are enforced whether or not anyone read your instructions, as in the guardrail hook walkthrough . A read-only worker should be read-only because it only has Read, Grep, Glob, not because CLAUDE.md asks nicely.

The same logic runs the other way. If a rule matters enough to enforce, it shouldn’t live only in a file a subagent can skip.

Carrying the rules in the prompt instead

If a worker needs three rules out of a hundred, send the three. A delegation prompt that does this is short and explicit:

Use the log-summariser subagent on build.log. Report the first failing
step and the error line, nothing else. Ignore warnings from vendor/.
Don't suggest fixes.

That prompt costs about forty tokens and replaces thousands. It also makes the contract visible: when a result looks wrong, the whole of what the worker knew is in one place, instead of spread across four instruction files. That’s a debugging advantage on top of the saving.

If you spawn the same worker constantly and the three rules never change, move them into the subagent’s own markdown body. The body is its system prompt, so the rules travel with the agent and don’t depend on anyone remembering to restate them.

Other startup context you can trim or ignore

CLAUDE.md is the biggest default, but the docs list the rest of what a non-fork subagent starts with, and a few points are worth knowing:

  • Git status is a snapshot taken when the subagent starts. You can’t turn it off per subagent; only Explore and Plan skip it.
  • Skills in the skills field are injected in full at startup. Preload only what the worker needs, because every preloaded skill is context it carries from turn one.
  • Your main session’s auto memory isn’t loaded into subagents. A subagent can have its own through the memory field, which is a separate directory.
  • Your output style doesn’t apply to subagents either, since they run their own system prompt.
  • A subagent’s context window is sized by its own model, not yours. Delegating to a model with a smaller window gives the worker the smaller window, so a bloated startup context hurts more there.

The one that surprises people is the first. If you wanted a subagent that starts nearly empty, omitClaudeMd plus a tight tools list plus no preloaded skills gets you close, but git status and the harness’s environment notes stay.

Try it

Pick the subagent you spawn most often that only summarises or searches. Add omitClaudeMd: true to its frontmatter, run it on a real task, and check whether the answer changed. If not, leave the flag on and keep the tokens.