Claude Code in a monorepo: the repo is big, the task is not

The ticket was a one-line validation fix in packages/billing. The agent spent its first five minutes elsewhere: the mobile app, the design system, an abandoned prototype called web-old. By the time it found the right file it had burned half its context on code that was never going to change, and its opening suggestion imported a helper from a package billing is not allowed to depend on.

Nobody did anything wrong. You pointed a fast reader at four hundred thousand lines and said "somewhere in here is a small job." A monorepo hands an agent maximal freedom at the exact moment it needs maximal focus.

The fix fits in a sentence you will reuse weekly: the repo is big, the task is not. Set up the repo, and every session you open in it, so the agent sees one package sharply and everything else as a contract.

Why a monorepo overwhelms a coding agent

An agent orients the way a new hire does: it reads. In a single-app repo nearly everything it reads is relevant. A monorepo inverts the odds. Forty packages, three deploy targets, years of migrations, and somewhere in there the four files that matter. The context window fills with plausible neighbors, and a bloated context quietly degrades the agent long before it is technically full.

The second trap is quieter: in a monorepo, everything is editable. When the assigned package will not compile, the shared types package is right there, and editing someone else's contract is the shortest path to green. Compilers do not teach ownership. A capable agent will find that path.

Both traps are too much scope, so the setup below is one idea applied three times: shrink what the agent owns.

One CLAUDE.md at the root, one per package

Claude Code loads instruction files hierarchically: the root CLAUDE.md always applies, and when you work inside packages/billing, that package's own CLAUDE.md loads alongside it (the memory docs cover the lookup order). That hierarchy is the monorepo feature, so use each level for what only it can say.

The root file is repo law. The package manager and workspace tool, how to run a scoped test (pnpm --filter <pkg> test, not the world), and the boundaries: never edit a package the task did not name, never touch generated folders, changes to packages/shared require running its consumers' tests.

The package file is local knowledge. The framework, the test runner's quirks, the naming conventions, the one folder in this package nobody may touch. The craft of writing these files is its own subject, but the monorepo rule is simple: a rule that is true everywhere goes in the root, a rule about one package goes next to that package, and a root file that names individual packages is a smell.

Run /context and check which files loaded. If a billing session is carrying the frontend team's rules, rent is being paid on instructions that cannot help.

Scope the session to the package, not the repo

Where you start the session is a scoping decision. Open Claude Code in packages/billing and that directory is the working world: its CLAUDE.md loads, searches default to the right subtree, and the brief gets shorter because the location already says most of it. The official guide to large codebases pushes the same direction: narrow the working set before asking for work.

Then let the brief finish the job. Name the package, name the boundary: "Fix the rounding bug in packages/billing. Do not modify other packages; if a fix requires it, stop and say so." That last clause turns the worst failure mode into a report you can act on.

Cross-package features do not break the model, they just refuse to be one task. Change the shared contract first, in its own session, judged by its own standard (every consumer still compiles and passes). Then fan out one package-scoped task per consumer. It is ordinary task breakdown with the package graph as the seam, instead of one heroic session wandering six packages with a full context and no owner.

Shared code deserves the bluntest version of the rule: treat it as an API with other customers, not a shortcut to green. An agent may read it freely and change it only when changing it is the task.

Where monorepo agents go wrong

The honest section, as symptoms, because that is how you will meet them:

• The context is full and the diff is empty. Ten minutes in, the agent is still summarizing packages. It started at the root with no map. Start it in the package, and let the hierarchy load only what this task needs.
• Your package is green, three others are red. The agent "fixed" a shared package to make its build pass, and the blast radius surfaced in Monday's CI. That is the missing root-law line about shared consumers, plus a brief that never named a boundary.
• Two agents, one tree, crime-scene git status. Package scoping narrows collisions but one working tree is still one working tree. When several agents write at once, give each its own checkout with git worktrees.
• The root file became a novel. Every incident added a rule, and now every session in every package pays for all of them. Push rules down to package files until the root holds only what is true everywhere.

One board for the repo, one session per package

Scoping works, and it multiplies sessions: billing here, the design system there, a shared-contract change waiting on both. A pile of terminal tabs is where that clarity goes to die, which is the reason SanuDesk exists.

It is a desktop app that tiles your Claude Code, Codex and Gemini sessions into one grid, so per-package sessions sit side by side, not behind each other. The Kanban board holds the work: each card is a package-scoped brief, deploying it opens a fresh session already pointed at the right folder, and when the agent stops, the card parks in a review lane with a note on what changed. The cross-package fan-out becomes visible instead of mental: one card per consumer, moving across the board independently. Repo-wide chores (the nightly lint sweep, the dependency bump that walks package by package) become Loops that run on a schedule and journal every run. It is bring-your-own-model, driving the agent subscriptions you already pay for, and the grid and board are in the free plan (details on pricing).

The repo stays one repo. The work finally ships in package-sized pieces.

Shrink one package this week

Pick the package you touch most. Give it a ten-line CLAUDE.md: test command, two conventions, one boundary. Add the shared-code law to the root file. Then open a session inside that package, hand it one real task, and when it finishes, count the files it touched outside the package. The number you are after is zero, and once you have seen it, root-level sessions start feeling like handing a stranger your whole keyring.

Download SanuDesk free to give every package its own tile on the grid, or see how the board, grid and Loops fit together on the features page.