Clogmeter
See what your CLAUDE.md files cost before they load → Paste the root file, then each folder file, into the free CLAUDE.md token counter to see lines and tokens against the 200-line target. Runs in your browser; nothing is uploaded.

Home · Guides · Tuesday 17 Nov 2026 · Clogmeter team

When does Claude read CLAUDE.md files (and which does it read)?

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 rootCLAUDE.mdpackages/api/CLAUDE.md when Claude reads or edits a file in packages/api/; the same for webAny package Claude never touches
packages/api/Root CLAUDE.md, then packages/api/CLAUDE.mdSubfolders of packages/api/ that have their own filepackages/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 itEach repo’s CLAUDE.md, once Claude works on a file in that repoRepos 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

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

  1. Run /memory or /context all. The monorepo guide says /context all lists loaded files under Memory files. Run it again after Claude has worked in a subfolder.
  2. Log it with the InstructionsLoaded hook. It fires when a CLAUDE.md or rules file loads, at startup and on lazy loads, with a load_reason such as session_start or nested_traversal.
  3. 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

  1. Keep the root CLAUDE.md to rules that apply to every task.
  2. Move package- or folder-specific rules into that folder’s CLAUDE.md, or a path-scoped rule.
  3. Launch from the package when the work stays inside it, and from the root when it spans packages.
  4. Use claudeMdExcludes in .claude/settings.local.json to skip other teams’ files you never need.
  5. Weigh each file in the AGENTS.md / CLAUDE.md token counter (or the Cursor rules token counter for .mdc files), then paste them all into Clogmeter to flag duplicates and always/never conflicts between the root and folder files.
Open Clogmeter and weigh your instruction files → Free, browser-only. See tokens, context share, duplicates and conflicts across files.

No spam. Unsubscribe anytime. We never share your email.