Layered CLAUDE.md token cost: the file you pasted is one layer of the bill.

You pasted your CLAUDE.md into an analyzer, saw a token number, and felt either fine or guilty. Either way the number was wrong, because it measured one layer of a stack. Claude Code does not load a CLAUDE.md. It walks up the directory tree and concatenates every CLAUDE.md it finds, expands every @import, and prepends your machine-wide user file, all before it reads a line of your code. This page is the arithmetic nobody else does: how to add up the layers and get the real per-turn cost.

1. The analyzer scores one file

Start with the tool, because the tool is honest about its scope. ccmd's analyzer, the one behind the textarea on ccmd.dev, takes a single string and returns a single score.

That is the right unit of analysis. A file is a file. But it means the token number you get back is the cost of that file, not the cost of opening Claude Code in that repo. Those are different numbers, and on most machines they differ by more than 10x. The analyzer is not hiding the rest of the stack from you. It simply never saw it, because you only pasted one layer.

2. ccmd's own repo: a 3-token paste, a ~4,980-token floor

The cleanest demonstration is the repository this site is built in. Its project CLAUDE.md is 11 bytes. The whole file:

One line. That is the canonical pattern from Anthropic's memory docs: if a repo already has an AGENTS.md for other coding agents, you write a CLAUDE.md that imports it with @AGENTS.md so both tools read the same instructions. Paste that 11-byte file into the analyzer and it scores it at 3 tokens. The analyzer is correct. The file is 3 tokens. It is also nowhere near what Claude Code loads when you open this repo.

Where does ~4,982 come from? Three files, all loaded in full at launch, every one of them sitting in context on every turn:

• ./CLAUDE.md — 11 bytes, 3 tokens. The @AGENTS.md import line.
• ./AGENTS.md — 327 bytes, 82 tokens. Pulled into context by that import, expanded inline at launch.
• ~/.claude/CLAUDE.md — a real user file on a working machine measures 19,586 bytes, about 4,897 tokens by the analyzer's chars / 4 heuristic. It loads in every repo on that machine, and you almost never think about it.

The project file you would naturally paste is the smallest layer by three orders of magnitude. The layer that dominates the bill is the one you have not opened since you set up your machine.

3. Watch the layers add up

Same repo, played as a sequence. Each frame is one thing Claude Code does at launch, with the running token total.

Prompt caching claws most of that back on turns where the prefix is byte-identical, and the three cost states guide does that math. But caching divides the layered total. It does not change which layers are in it. A cache hit on a stack you mismeasured still mismeasures the stack.

4. Which layer loads, and when

Not every layer behaves the same. Two load conditionally, the rest load at launch and never leave. The distinction is the whole game for cost, so here it is in one table.

Read the first six rows again. That is the most expensive sentence in this whole topic: an @import does not reduce token cost. The most repeated piece of layering advice online is "split your CLAUDE.md into imports to keep it lean." Anthropic's memory docs say the opposite, in plain words: imports help organization "but does not reduce context, since imported files load at launch." The expanded content enters context exactly as if you pasted it inline. A three-line root file that imports a 4,000-token file costs 4,000 tokens a turn, not three.

The one genuine layering win is the second-to-last row. Subdirectory CLAUDE.md files load on demand, only when Claude opens a file in that directory. In a monorepo, a per-package file defers its cost until you work in that package. That is the only nesting move that actually lowers your floor. If a guide tells you nesting saves tokens without naming the on-demand mechanism, it has conflated the two and you should not trust its arithmetic.

5. Measure your real layered total

The analyzer takes one file, so feed it the layers one at a time and sum. The terminal command that lists the byte sizes, then the analyzer's own token math on each:

The procedure, four steps, no signup:

1. Paste ~/.claude/CLAUDE.md into the analyzer on ccmd.dev. Write down the token count. This is the layer that repeats in every repo, so it is worth getting honest about first.
2. Paste your project ./CLAUDE.md. If it contains @import lines, open each referenced file and paste those too. Follow the chain up to five hops deep.
3. Paste any .claude/rules/*.md file that has no paths: frontmatter. Those load unconditionally too.
4. Add the token counts. That sum is your per-turn floor. Multiply by turns per session, then by sessions per week, for the number you can put in front of a teammate.

One precision note. The analyzer counts raw characters, and Claude Code strips block-level HTML comments before injecting a file, so a file heavy with <!-- ... --> maintainer notes scores slightly high per layer. That is a rounding error. The layer you forgot to paste at all is the real mistake.

6. The layer you forgot, and how to cut it

In practice the forgotten layer is one of two. The first is your own ~/.claude/CLAUDE.md. It grows the way a junk drawer grows: one preference at a time, never reviewed, and it taxes every project on the machine. If it has drifted past a couple thousand tokens, that is the highest-leverage file to audit, because the saving multiplies across every repo you touch.

The second is a layer you cannot edit: an ancestor CLAUDE.md from another team, picked up by the upward directory walk in a shared monorepo. For that, Anthropic's docs describe claudeMdExcludes, a setting that skips specific CLAUDE.md files by path or glob. Put it in .claude/settings.local.json so the exclusion stays on your machine and does not change anyone else's context. The one layer no setting can drop is a managed policy file: that one is deliberately not excludable.

The takeaway is small and it is the whole page. A token number is only as good as the question it answered. "How big is this file" and "what does opening Claude Code in this repo cost" are different questions. The analyzer answers the first precisely. The second is a sum, and now you know every term in it.