AI Coding in Monorepos: Token Cost Math for Multi-Package Repos vs Polyrepo
By Eric Bush · July 1, 2026 · 9 min read
Why Monorepos Cost More per Agent Task
An agent working on a single-purpose repo can build a mental model of the codebase in one or two Read passes. An agent working on a 15-package Nx monorepo has to first figure out which package(s) it cares about, then load context from potentially multiple packages plus their shared dependencies.
Real observation from tracing agent sessions across both patterns:
| Repo shape | Median input / task | Investigation overhead |
|---|---|---|
| Single-repo, small (<10 files) | 45K | ~10% |
| Single-repo, medium (<500 files) | 120K | ~25% |
| Monorepo, 5-package | 380K | ~45% |
| Monorepo, 15+ package | 720K | ~55% |
| Monorepo with sparse checkout | 160K | ~20% |
“Investigation overhead” is the percentage of input tokens spent on directory listings, cross-package searches, and dependency resolution rather than the actual code the agent will modify. In a 15-package monorepo, more than half of every prompt is context the agent probably doesn't need.
Cost Impact on Common Workflows
Take a medium-complexity feature build. Token profiles at Claude Sonnet 5 promo pricing ($2/$10 per M):
| Setup | Cost per feature | Cost per 100 features |
|---|---|---|
| Polyrepo (small repos) | $0.32 | $32 |
| Monorepo (default) | $1.85 | $185 |
| Monorepo (with sparse checkout) | $0.48 | $48 |
Across 100 tasks the delta is ~$150. Across 1,000 tasks it's $1,500. For any team working on a large monorepo, sparse checkout for agent sessions is the highest-ROI configuration change available.
Sparse Checkout for Agent Sessions
Sparse checkout is a git feature that lets you materialize only part of a repo on disk. For agent sessions, this means the agent sees only the packages relevant to the task, cutting investigation overhead dramatically.
Practical setup for a Turborepo or Nx workspace:
git clone --filter=blob:none --sparse https://github.com/org/monorepo
cd monorepo
git sparse-checkout set apps/web packages/ui packages/configThe agent starts up with only the paths it needs. If it discovers it needs another package, you extend the sparse-checkout set on the fly. This trades a small setup cost (deciding which packages to include) for a large per-session savings.
When the Monorepo Still Wins
Monorepos exist for good reasons — atomic cross-package changes, single-source-of-truth versioning, shared build pipelines. AI coding cost isn't the only variable. The monorepo advantages that still hold:
- Cross-package refactors. One agent session can update a shared type across every consumer. In polyrepo land this becomes N coordinated PRs.
- Dependency drift prevention. Shared versions are guaranteed rather than curated.
- Cache reuse for CI. Turborepo cache benefits both human and agent workflows.
The right question isn't “monorepo or polyrepo?” but “how do we structure the agent's view of the monorepo?” Sparse checkout gets you the coordination benefits without the token cost.
Additional Optimizations Specific to Monorepos
- Package-level CLAUDE.md. Beyond the root instruction file, each package can have its own scoped one. Agents working in that package pick up local context without global bloat.
- Nx project graph as agent input.
nx graph --file=graph.jsonoutputs the dependency graph. Providing this saves the agent from having to reconstruct it from tsconfig paths. - Excluded paths. Add build outputs, generated code, and third-party vendored deps to
.claudeignoreor equivalent. These are the biggest silent context bloaters. - Per-package agent sessions. When a task is genuinely scoped to one package, spin up the agent inside that package's directory rather than the workspace root.
Decision Framework
For any given task, ask three questions:
- Is this task scoped to 1–2 packages? → Sparse checkout or per-package session.
- Does this touch shared types or contracts? → Full monorepo view, but pre-load the dependency graph.
- Is this a cross-cutting refactor? → Full view. Accept the token cost; the coordination win is bigger.
The default of “always load the whole monorepo” is the most expensive setup you can pick. A few config decisions turn it into the cheapest.
Want to calculate exact costs for your project?
Frequently Asked Questions
Are monorepos more expensive for AI coding agents than polyrepos?
By default, yes — often 4–6× per task due to investigation overhead. Sparse checkout closes most of the gap while preserving monorepo's cross-package coordination benefits.
How does sparse checkout help with agent token costs?
It restricts the on-disk view to only relevant packages, so the agent's directory listings and searches touch a fraction of the codebase. Investigation overhead drops from ~55% to ~20%.
Should each package in a monorepo have its own CLAUDE.md?
For large monorepos, yes. A root CLAUDE.md covers workspace-wide rules; per-package files add local context without bloating the global one. Agents pick up both.
Does Turborepo or Nx affect agent costs differently?
They both have similar structural cost profiles. Nx's project graph is easier to hand to an agent as pre-computed context. Turborepo's simpler layout wins slightly on default agent runs.
When should I split a monorepo back into polyrepo just for AI coding cost?
Almost never. Sparse checkout, package-level instruction files, and dependency-graph pre-loading close the cost gap. Don't restructure your repo strategy around this — configure your agent workflow instead.
Related Articles
Every's Compound Engineering: How One Engineer Runs Five Products at 80% Non-Coding Time — Real Token Math
Every, the media-software company, runs five products with a single engineer who spends 80% of time on Plan and Review, only 20% writing code. We break down the Plan → Work → Review → Compound loop, the CLAUDE.md maintenance cost, and where the ROI crosses over.
AI Coding Cost per Commit: Token Math for Feature Branches vs Main Merges
Not all commits cost the same. A one-line typo fix, a feature branch merge, and a refactor commit have wildly different token profiles when generated by AI. We break down the real per-commit cost across commit types and how to track it.
AI-Generated Release Notes and Changelogs: Cost per Release Token Math
Every release needs notes. Generating them from AI takes tokens — but how many depends on whether you feed the model Conventional Commits or the full diff. We break down the cost per release across strategies and where each pays off.