How Do I Keep Claude Code Lean in a Large Monorepo?

The first time you run Claude Code on a real monorepo, the context usage chart looks like a Black Friday traffic graph. A single "explain how this feature works" question pulls in 40 files, and you're staring at a 150k-token conversation before Claude has typed a word. Here's how to keep Claude Code useful on a huge codebase without eating through your token budget, or your patience.

Why this matters

Claude Code is a great collaborator on small projects and a great collaborator on big projects if you configure it correctly. Out of the box, it defaults to reading liberally: the file you referenced, its imports, related test files, CLAUDE.md, and whatever else it thinks relevant. That's the right default on a 50-file project and the wrong default on a 50,000-file monorepo.

With the right configuration, scoped attention, targeted rules, aggressive context management, Claude Code stays precise on a monorepo. You get the speed you want without the token bill you don't.

Before you start

You need:

• Claude Code 1.5+ installed and working on a large repo.
• A monorepo you actually work in. The guide makes more sense with a concrete codebase to configure against.
• 30 minutes. Mostly in config files.

Step 1: Understand what Claude reads by default

Run /context in an active session. Claude shows you exactly what's in its current window:

• CLAUDE.md files (root + any parent/subpath).
• Files you've mentioned or Claude has opened.
• Tool definitions.
• The conversation so far.

Look at the line counts. On a monorepo, you'll often see dozens of files loaded from "looking around," many irrelevant to the task. That's the problem to fix.

Step 2: Scope with a monorepo-aware CLAUDE.md

At the repo root, your CLAUDE.md should be small, only truly repo-wide rules. Monorepo context belongs in sub-path CLAUDE.md files:

Claude walks the directory tree from the file it's editing, reading every CLAUDE.md along the way. So when you're editing in apps/web/, Claude reads apps/web/CLAUDE.md + CLAUDE.md, not apps/api/CLAUDE.md.

This alone cuts CLAUDE.md overhead by 60-70% in a typical monorepo.

Step 3: Configure an ignore list

Claude Code respects a .claudeignore (or equivalent, check your version's name). Use it like .gitignore:

Anything in .claudeignore is invisible to Claude, no reads, no greps, nothing. Scoping to the app you're actually working in is the biggest single token win.

For per-session scoping, some versions let you pass --project-dir apps/web to launch Claude Code already scoped to that sub-app. If available, use it for narrow-scope sessions.

Step 4: Avoid open-ended exploration prompts

Prompts like "give me an overview of this codebase" are monorepo budget-killers. Claude will try to read dozens of files to answer, costing you tokens and rarely producing insight you didn't already have.

Replace with scoped questions:

• "How does apps/web/src/app/api/checkout/route.ts handle the webhook signature?"
• "Find all uses of useAuth() in apps/web/ and list them."
• "Summarize the changes in the last 3 commits that touched packages/ui/."

Specific location + specific question = a small, focused read. Claude answers in a few file reads instead of forty.

Step 5: Use /compact or /clear aggressively

Claude Code has commands to reduce the live context:

• /clear, wipes the conversation history, keeping only CLAUDE.md and current task. Use between distinct tasks.
• /compact, asks Claude to summarize the current conversation into a shorter form, replacing the verbose history. Use mid-task when context is getting heavy.

Rule of thumb: if a conversation has 30+ turns of tool use, /compact. If you're starting a new task (different feature, different app), /clear.

Step 6: Scope tool use with rule files

For very large repos, limit what Claude can read via permission rules. In .claude/settings.json (or your version's config path), restrict Read and Glob to paths you're working in:

Now Claude physically cannot read the parts of the monorepo you're not working in. Safer and cheaper.

Check your Claude Code version's docs for the exact permissions format, it's stabilized but the key names can shift.

Step 7: Cache what's stable

For long sessions in a big repo, the initial context (CLAUDE.md + tool definitions) is stable while the conversation grows. That's a prompt caching opportunity, see How Do I Keep My Claude Prompt Cache Hit Rate High?, though Claude Code handles caching under the hood on supported models. Verify in your session logs that cached reads are happening; if not, update to the latest Claude Code.

Step 8: Build a "starting prompt" that skips orientation

Instead of letting Claude figure out where to start on every task, give it a preamble:

You've done the orientation Claude would have paid 20 file reads to do. The task proceeds from a small, correct initial context.

Verify it worked

1. Cold-start context is small. Open a fresh Claude Code session, type /context. Line count should be under a few thousand, mostly CLAUDE.md and tool definitions, not app code.

2. Tasks finish with fewer file reads. A medium task that used to take 40 Read tool calls should now take 10-15. Watch the tool-use indicators.

3. Cost per session drops. If you're on API billing, compare a typical session's cost before and after configuration. Target: 50%+ reduction.

Where this breaks

• Ignoring files you actually need. A .claudeignore that excludes packages/shared/ means Claude can't see your shared utilities, which are probably relevant. Start permissive, tighten as you notice over-reads.
• Stale sub-path CLAUDE.md files. Conventions evolve; sub-path CLAUDE.md files get stale fast because nobody looks at them unless they're actively working there. Add a reminder in root CLAUDE.md: "Sub-path CLAUDE.md files exist at X, Y, Z, keep them current."
• Claude hallucinating about code it can't see. When you restrict reads aggressively, Claude sometimes confidently describes code it didn't actually read. Ask "show me the line you're referring to", if Claude can't cite, it was guessing. Widen the scope if this happens often.
• Per-app permissions drift from actual app structure. Adding a new sub-app that isn't in the allowlist means Claude can't see it on day one. Update .claude/settings.json when you add apps, same time you update other repo-level configs.
• Compact losing important context. /compact is a summary, not a lossless compression. Details in the compacted portion can disappear. Don't compact right before a precision task; compact after.

What to try next

• How Do I Write a CLAUDE.md That Actually Changes Claude's Behavior?, the foundation of per-sub-path scoping.
• How Do I Keep My Claude Prompt Cache Hit Rate High?, the cost lever that matters most on long Claude Code sessions in big repos.
• How Do I Set Up Claude Code Hooks for Auto-Quality?, quality gates matter more in a big repo where a small mistake can cascade. Hooks run the gates automatically.