Large codebases

A monorepo is a single repository holding many packages, large enough that the reading and searching Claude Code does by default turn expensive.

Last updated: 28 Sep, 2026 · Claude Code

Everything so far worked on three files. The defaults that make that pleasant are the same defaults that fill a context window in ten minutes on a monorepo.

Nothing breaks at scale. What changes is that reading becomes expensive, one CLAUDE.md covering every subsystem becomes noise, and a search that matches four hundred files stops being useful. Each of those has a fix, and they layer.

Put the conventions next to the code

The memory lesson said files in subdirectories load when Claude reads something in that directory. In a monorepo, build on that: a small root CLAUDE.md for what is true everywhere, and a file per package for what is true there.

Skills work the same way. A per-directory skill for the deployment procedure of one service loads when that service is the work, and costs nothing the rest of the time.

Stop it reading what it should not

Build output, generated code and vendored dependencies are the biggest waste in a large repository, and deny rules are the cheapest fix in this course.

json

{
  "permissions": {
    "deny": [
      "Read(**/dist/**)",
      "Read(**/node_modules/**)",
      "Read(**/*.generated.*)"
    ]
  }
}

The rules from the settings.json lesson with a different purpose: not safety, cost. A generated file read into context is money spent on something no human would have opened.

Give it less to look at

Problem	What helps
Worktrees check out everything	`--add-dir` or starting Claude in the package directory, so it works over only the directories the task needs
It scans files to find a definition	A code intelligence plugin, which answers from the language server instead
The task needs a sibling package	`--add-dir`, or `additionalDirectories`, rather than starting at the repository root
Irrelevant CLAUDE.md files load	`claudeMdExcludes` for packages you never touch

Where you start the session matters more than any of them. Starting in the package you are working on, rather than at the root, changes what loads, what gets searched, and which settings apply.

Measure first

The signal to act is /context, from the context window and compaction lesson. When most of the window is files you did not need, one of the fixes above is the answer, and which one is usually obvious from what is in there.

Try it yourself

Run /context in your largest repository after a normal task.
Add one deny rule for your build output and repeat the task.

PreviousRoutines and scheduled tasks

This is what real progress feels like.

Large codebases

Put the conventions next to the code

Stop it reading what it should not

Give it less to look at

Related