Claudemd Deep Dive

How Claude Code Reads CLAUDE.md Files — Experiment

Claude Code supports `CLAUDE.md` files at multiple levels. Global and project-root files are simple — loaded once at session start, always in context. Subdirectory files are different: the docs say they load *"on demand as Claude navigates your codebase"* but explain nothing about the actual mechanism.

We had questions that mattered for building agents:

• What exactly triggers the load — any tool, or a specific one?
• Does it re-inject on every file read, or is there deduplication?
• Where does the content go — system prompt or messages?
• What survives a session resume?
• Does repeated injection blow up token costs?

To answer these we put an intercepting HTTP proxy between Claude Code and the Anthropic API and traced every `/v1/messages` call. Full write-up: **[REPORT.md](./REPORT.md)**

---

Key Findings

Question	Answer
What triggers subdir CLAUDE.md?	Read tool only — not Bash, Glob, or Write
Where does it appear?	Concatenated into the tool result text — not the system prompt, not a separate message
Does system prompt grow?	Never — stays constant regardless of how many subdirs load
Re-injected on every Read?	No — once per subprocess per directory (readFileState Map)
Visible after injection?	Yes — sticky in message history for all subsequent turns
Parallel reads, same dir?	One injection total for the whole batch
Persisted to disk?	Stripped before writing — disk session is always clean
Session resume?	readFileState resets → fresh injection on first Read
Token cost?	Near-zero — prompt caching absorbs it

---

Repository Structure

Experiment scripts

File	Description
src/experiment.ts	Experiment 1 — 9 scenarios covering first Read, same-session re-read, new session, multiple subdirs, Write-only, Glob-only, Bash-only, and resumed session. Outputs results.json.
`src/exper