Claude Code reads CLAUDE.md in your launch folder and every folder above it at startup, and a subfolder CLAUDE.md only once it works on a file there. Here's what loads, when, what it costs, and how to check.
Originally published on clogmeter.vercel.app.
Claude Code reads every CLAUDE.md and CLAUDE.local.md in the folder you launch it from and in every folder above it, at the start of the session. A CLAUDE.md in a subfolder below where you launched is not read at startup; it loads the first time Claude reads, writes or edits a file in that subfolder. Your personal ~/.claude/CLAUDE.md loads every session. Folders that are neither above nor below your launch folder are not covered by either rule, so their CLAUDE.md files don't load by default.
The question is the title of an r/ClaudeCode thread: "When does Claude read CLAUDE.md files (and which does it read)". The poster launched Claude in a parent folder that held several repos, and was surprised that one repo's CLAUDE.md only showed up once Claude started working on files inside that repo. That is the documented on-demand loading for subfolders, described below.
Loading behaviour is quoted from Anthropic's Claude Code memory docs, the monorepo guide, the tools reference and the hooks reference (checked 17 Nov 2026). Claude Code changes often; confirm on your version with the checks at the end.
The three rules
| Where the file is | When it loads |
|---|---|
| Your launch folder and every folder above it |
At startup. All of them are concatenated, not overridden, ordered from the filesystem root down to your launch folder, so the file nearest to where you launched is read last. In each folder, CLAUDE.local.md comes after CLAUDE.md. |
| A subfolder below your launch folder |
On demand, once Claude reads, writes or edits a file in that subfolder. A single-file Bash view such as cat or head counts as a read. |
~/.claude/CLAUDE.md |
Every session, in every project. |
Anything else, such as a sibling package or a repo you reach with --add-dir, isn't loaded by default. The docs say --add-dir folders don't load their CLAUDE.md unless you set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.
Worked example: one monorepo, three launch folders
Take a repo with CLAUDE.md, packages/api/CLAUDE.md and packages/web/CLAUDE.md.
| You launch in | Loaded at startup | Loaded later | Not loaded |
|---|---|---|---|
| repo root | CLAUDE.md |
packages/api/CLAUDE.md when Claude reads or edits a file in packages/api/; the same for web
|
Any package Claude never touches |
packages/api/ |
Root CLAUDE.md, then packages/api/CLAUDE.md
|
Subfolders of packages/api/ that have their own file |
packages/web/CLAUDE.md (a sibling, neither above nor below) |
| A parent folder holding several repos (the Reddit case) | The parent's CLAUDE.md, if any, and anything above it |
Each repo's CLAUDE.md, once Claude works on a file in that repo |
Repos Claude doesn't open |
Anthropic's monorepo guide describes the second row: start in packages/api/ and Claude sees the local instructions alongside the repo-wide rules, "with no instructions from packages/web/ in context." It suggests launching at the root when tasks span several packages, and in a package when the work stays inside it.
What this means for token cost
-
Startup files are paid for every session. The root file and everything above your launch folder load before you type anything. Anthropic's target is under 200 lines per
CLAUDE.md. -
A folder file costs nothing until Claude works in that folder. That makes subfolder
CLAUDE.mdfiles a good home for rules that only matter in one area..claude/rules/*.mdfiles withpaths:frontmatter do the same job for file patterns. -
Imports don't save tokens.
@pathimports load together with the file that imports them (up to four hops deep). They tidy a long file; they don't make it cheaper. -
Big on-demand files get cut off. A subfolder
CLAUDE.mdor on-demand rules file over a per-file size limit (40,000 characters with a 200K context window) is truncated, and Claude gets only the start until it chooses to read the rest. Check withwc -m. -
HTML comments are free. Block-level
<!-- notes -->are stripped before the content reaches Claude, so maintainer notes don't spend context.
After /compact
The docs say the project-root CLAUDE.md is re-read from disk and re-injected after /compact. Subfolder CLAUDE.md files and path-scoped rules don't come back straight away; they load again the next time Claude works on a matching file. If an instruction seems lost after compaction, check whether it lives in one of those.
Where AGENTS.md fits
In current versions Claude Code can read AGENTS.md, but by default only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your launch folder or above it. When it does, it reads the AGENTS.md files in your launch folder and above at startup, and a subfolder's AGENTS.md when Claude opens a file there with the Read tool, provided that subfolder has no CLAUDE.md of its own. If you keep both, an @AGENTS.md import in CLAUDE.md is the documented way to share one file. See CLAUDE.md vs AGENTS.md.
How to check what actually loaded
-
Run
/memoryor/context all. The monorepo guide says/context alllists loaded files under Memory files. Run it again after Claude has worked in a subfolder. -
Log it with the
InstructionsLoadedhook. It fires when aCLAUDE.mdor rules file loads, at startup and on lazy loads, with aload_reasonsuch assession_startornested_traversal. - Don't ask Claude. A model asked about its own prompt can give misleading answers, as a reply in the Reddit thread points out. Use the commands or the hook.
Users have reported gaps in the on-demand trigger. For example, anthropics/claude-code#90449 reports that piped or multi-file Bash commands and Bash writes don't load a subfolder file. The tools reference lists the Bash views that count as a read: cat, nl, bat, head, tail, sed -n, grep and rg, run on one file with no pipes or redirects. If a folder's rules really must apply, test it with the hook rather than assuming.
Quick setup that works with these rules
- Keep the root
CLAUDE.mdto rules that apply to every task. - Move package- or folder-specific rules into that folder's
CLAUDE.md, or a path-scoped rule. - Launch from the package when the work stays inside it, and from the root when it spans packages.
- Use
claudeMdExcludesin.claude/settings.local.jsonto skip other teams' files you never need. - Weigh each file in the free AGENTS.md / CLAUDE.md token counter (or the Cursor rules token counter for
.mdcfiles), then paste them all into Clogmeter to flag duplicates and always/never conflicts between the root and folder files.
If you want to see what your own CLAUDE.md, AGENTS.md or Cursor rules cost in tokens and where they repeat or contradict each other, we built a free browser-only checker: Clogmeter.
Top comments (1)
The launch directory acting as a context boundary is easy to miss when a shell or editor opens a monorepo from a parent folder. Pinning a repo-root launch command in the team docs and verifying loaded files with /context all makes “the rule was ignored” much easier to diagnose.