Claude Code choking on your monorepo? CLAUDE.md hierarchies fix it

A 500-file monorepo can burn 500K+ tokens in a single Claude Code request if you go in without a plan. Three things decide whether a large codebase stays workable: a layered hierarchy of agent rule files that loads only what fits the current task, a clear token budget so exploratory reads don’t eat your headroom, and subagents that keep cross-package research out of your main window.

The Context Window Reality

Context window sizes vary significantly by plan:

Since March 13, 2026, the 1M token window ships for both Claude Opus 4.6 and Claude Sonnet 4.6. Pricing stays flat past the 200K mark, with no premium tier.

A fresh Claude Code session costs about 20K tokens before you type a thing. That covers the system prompt, CLAUDE.md contents, and tool setup. It’s fine on a 1M window but eats 10% of a 200K budget right away. The rest (180K, or 480K and 980K on bigger plans) is what you have for reads, grep results, thinking, and output.

Claude Code does not pre-index your codebase or build vector embeddings. It uses three filesystem tools to explore code on demand: Glob for pattern matching, Grep for content search, and Read for loading files. Every file read draws straight from your budget. A single sweep across 30 TypeScript files (about 2K tokens each) costs 60K tokens. Add grep results at 1K each, and you can burn through half a 200K window before writing any code. Heavy token use like this became the top complaint in the Reddit reception of Claude Opus 4.7 , and the same token-burn gripe shaped which coder redditors preferred , so monorepo work makes budgeting non-optional.

Opus 4.6 scores 76% on the MRCR v2 (Multi-needle Retrieval) benchmark at 1M tokens. That’s a fourfold jump over Sonnet 4.5’s 18.5% at the same scale. Recall holds up at the far end of the window. But cost-per-request scales straight with tokens used, so efficiency still counts on the Max plan . Chasing the same savings through bargain token deals backfires, because the discount is paid for with your logged prompts.

CLAUDE.md Hierarchy: Layering Context Across Root and Subdirectories

A layered CLAUDE.md hierarchy that loads only what fits your current task is the highest-leverage change you can make. Claude Code reads CLAUDE.md files from the current directory and every parent, merging them. Launch from apps/web/ and it loads both the root file and apps/web/CLAUDE.md with no setup.

Root CLAUDE.md: Stay Under 150 Lines

The root file should hold only four things. What the codebase is, in 2-3 sentences. Universal rules like TypeScript strict mode, ESLint settings, and naming patterns. Files Claude must never touch. Common commands like pnpm turbo build and the test runner.

Anything past that belongs elsewhere. Put docs in docs/. Put step-by-step workflows in .claude/skills/. Park heavy API docs anywhere that isn’t loaded by default. Every line in your root CLAUDE.md gets paid for on every session start, and every subagent session too.

A 2,000-token CLAUDE.md loaded into every session adds up fast. Spawn five subagents per task, run 20 tasks a day, and that’s 200K tokens per day just to load the file. Keep it lean.

Package-Level Files: Scoped and Specific

Package-level CLAUDE.md files live in each workspace folder, like packages/ui/CLAUDE.md or apps/api/CLAUDE.md. They hold component rules, local test commands, package deps, and API patterns unique to that package. Aim for under 50 lines per file.

A monorepo where backend and frontend subagents load only their own rules, rather than one shared blob, can cut rule overhead by 4x. The upshot: sharper attention on the rules that count for the current task.

CLAUDE.md has four layers of precedence. Enterprise policy sits at the top, applied org-wide. Then ./CLAUDE.md for the project, committed to git. Then ~/.claude/CLAUDE.md for your personal defaults. Finally ./CLAUDE.local.md, gitignored, for local overrides.

Progressive Disclosure at Scale

For monorepos with 50+ packages, set up progressive disclosure in the root CLAUDE.md. Skip the per-package docs. Instead, tell Claude to read each package’s CLAUDE.md or run pnpm turbo graph when it needs to see cross-package links. The root file becomes a guide, not an encyclopedia.

Flip negative rules to positive ones where you can. “Don’t use var” forces Claude to parse two ideas. “Use const/let” says the same thing with fewer tokens and no ambiguity.

Subagents for Context Isolation

Subagents are your main lever for avoiding context exhaustion in monorepo work. Each subagent runs in its own window with a custom system prompt, its own tool list, and its own permissions. Tool calls and file reads stay inside the subagent. They never pile up in the parent session.

Use subagents for research, not implementation. A research subagent can scan dozens of files across packages to answer “which packages import the Button component and what props do they pass?” None of those file contents land in your main chat. The parent gets a clean summary, not raw files.

Cost shifts with model and task type. An exploratory subagent on Haiku runs about 5K tokens per call. A general-purpose Sonnet subagent burns 30-50K. The cheap-and-fast tier matters here, which is the niche the 4x-faster Gemini 3.5 Flash targets with quick output at low cost. Parallel subagents speed up cross-package work, but they scale token use the same way. Ten parallel package subagents spend tokens 10x faster than running them in sequence.

Skills passed to a subagent must be named directly. They don’t carry over from the parent session. Build package-scoped skills so subagents can use them without pulling context from other packages.

Context Compaction for Long Sessions

Context compaction, new in Opus 4.6, sums up and replaces older context when a chat nears a set limit. In benchmarks, this let agents finish jobs that would otherwise hit the wall, and it cut token use by up to 84%. A 400K context squeezed to 160K cuts input costs per turn by 60%. It also keeps requests under the 200K long-context threshold. For monorepo refactors that span hours, compaction is often the gap between a task that finishes and one that fails on the context limit.

Turborepo and pnpm Workspace Integration

Turborepo and pnpm workspaces are the main monorepo stack in the JavaScript and TypeScript world. The ClaudeLab Monorepo guide writes up several patterns worth using.

Document Build Order in Root CLAUDE.md

Document turbo.json task dependencies so Claude understands the build constraint graph. A typical setup:

build    → depends on ^build (builds dependencies first)
test     → depends on build
lint     → no dependencies (runs in parallel)
dev      → persistent, uncached

Without this, Claude may propose changes that break the dependency graph. For example, editing a shared package without forcing the downstream rebuilds.

pnpm Filter Patterns

Include pnpm filter examples in CLAUDE.md:

# Add a dependency to one package only
pnpm --filter web add package-name

# Run tests across all packages
pnpm --filter './packages/*' run test

# Install internal package dependency
# (reference as workspace:* in package.json)

Claude then follows these patterns instead of falling back to root-level installs, which break workspace isolation.

Change-Scoped Validation

Turborepo’s --filter='[HEAD^1]' option runs tasks only for packages that changed since the last commit. For cross-package refactors, this is the right validation step. It skips full monorepo rebuilds and flags regressions only in the touched packages.

A holistic refactoring prompt that works:

“Update the Button component API in packages/ui, then find and update all usages across apps/web and apps/mobile, run pnpm turbo build to catch type errors, and run pnpm turbo test --filter='[HEAD^1]' to verify no regressions.”

One prompt hands Claude the full scope, the right validation commands, and the filter that skips rebuilds of unchanged packages.

Remote caching via TURBO_TOKEN can cut CI time by 60-80% on large monorepos. Put your cache config in CLAUDE.md so Claude can fix stale cache issues with pnpm turbo clean or pnpm turbo build --force.

A Practical Token Budget for a 200K Window

On a 200K window, a typical cross-package refactoring task breaks down roughly like this:

That leaves just over half the budget for actual thinking and code. Workable, but only because the CLAUDE.md files stayed tight. A 500-line root file plus bloated package files could push the overhead past 50K tokens before any real work starts. Little room would be left for the task itself.

On a 1M window (Max or Opus 4.6), the same 30-file refactor uses under 10% of the budget. So plan choice shapes workflow, not just cost. On Pro, subagent isolation is close to a must for anything past a single package. On Max, you have enough headroom to let Claude roam.

Team-Level Token Hygiene

For teams, share CLAUDE.md templates across packages so every dev gets the same behavior. Enforce max line counts in CI with a simple check:

wc -l packages/*/CLAUDE.md

If some packages keep forcing pricey exploration, add tighter CLAUDE.md notes or pre-built skills for them. That cuts the reads Claude needs on each run.

Track token use across sessions to spot patterns. The goal is to see where tokens go before you assume a bigger window will fix it. Often, the real fix is a tighter CLAUDE.md, not a pricier plan. Teams that want to move high-volume exploratory reads off a metered API entirely can point a local model at the repo through one of the open-source inference runtimes and keep the cloud plan for the hard reasoning steps.

Where This Breaks Down

The biggest failure mode is using CLAUDE.md as documentation storage. Every line costs tokens on every session start. If a line would work just as well in a docs/ file Claude reads on demand, put it there. CLAUDE.md should hold only what Claude needs before it knows the task: conventions, commands, and boundaries. Not everything that might one day be useful.

Root CLAUDE.md sets the rules everyone follows. Package files add the specifics that count only in that package. Subagents soak up the cost of exploration and return clean summaries. Context compaction stretches session length without a one-to-one rise in cost. Each layer is worth only what it adds. A layer that is mostly docs pays token overhead it never earns back.

Monorepos are a real context challenge, and the token budget is the limit everything else orbits. Claude Code turns practical in repos with hundreds of packages once you stop fighting the budget and start designing around it. If your repo strains a 200K window, Codex CLI’s roomier context window starts at a 272K default that you can push to 1M tokens through config. Reddit’s hands-on testers hand GPT-5.6-Sol that same efficiency edge, rating the Codex model cheaper on tokens than Claude even while they give Fable the design win.