Monorepo vs polyrepo, with AI coding agents in mind
Monorepo vs polyrepo compared: atomic changes, code reuse, access control, tooling, plus how each layout affects AI coding agents like Claude Code.
A team moves an API field from user_id to account_id. In a monorepo, it's one pull request: the API, the web app, the mobile client, and the shared types, all updated together. In a polyrepo, it's four pull requests in four repositories, a compatibility window, and a release sequence someone has to coordinate.
That's the core trade-off. This guide compares the two using the Wikipedia overview of monorepos and Claude Code's large-codebase guide, checked on 16 November 2026.
The short answer
| Monorepo | Polyrepo | |
|---|---|---|
| Cross-project change | One atomic commit | Coordinated changes and versions |
| Code reuse | Shared libraries, used directly | Published packages, versioned |
| Refactoring | See and fix every caller | Callers live elsewhere |
| Access control | Read access to everything by default | Per repository, least privilege |
| Versioning | Often one version for all | Per project |
| Checkout and storage | Everything by default | Only what you need |
| Tooling | Needs build tools that scale | Simpler per repo |
A monorepo isn't a monolith. Wikipedia notes a monorepo can hold many independent, even unrelated, projects; each can still build and deploy on its own.
Monorepo advantages
From Wikipedia's list:
- Code reuse: shared functionality lives in libraries projects include directly.
- Simpler dependency management: shared dependencies built once.
- Atomic commits: related changes across projects land together, avoiding version mismatches.
- Large-scale refactoring: you can see every user of a component and keep them working.
- Cross-team collaboration: teams can improve each other's code.
Monorepo disadvantages
- Versioning: some setups use one version for everything, losing per-project semantic versions.
- Access control: contributors can read everything by default, which conflicts with least privilege.
- Storage: you check out all projects unless your tools support partial checkouts.
- Scale: large monorepos push build and version control tools to their limits.
How each affects AI coding agents
Agents work from what they can read. That changes the calculation.
In a monorepo, an agent changing a shared type can find and update every caller in one session, and run every affected test. The risk is noise: thousands of files, many irrelevant. Claude Code's guide gives specific tools:
| Problem | Claude Code feature |
|---|---|
| One root file can't cover every package | Per-directory CLAUDE.md files, loaded for the code you touch |
| Packages you never work in | claudeMdExcludes |
| Generated and vendored code | Read deny rules in permissions.deny |
| Scanning files to find symbols | A code intelligence plugin |
| Worktrees with the whole repo | worktree.sparsePaths |
| Work scoped to one package | Start Claude in that subdirectory |
In a polyrepo, an agent in one repository can't see the API it calls in another. It guesses at contracts or needs access granted with --add-dir or additionalDirectories. Shared conventions have to be copied to each repo or packaged as a plugin.
Which to choose
- Teams shipping one product with shared code: a monorepo usually pays off.
- Strict access boundaries, such as contractors or regulated code: polyrepo, or a monorepo with strong tooling.
- Independent products with separate teams and release cycles: polyrepo.
- Heavy use of coding agents across services: lean monorepo, with layered instruction files.
What neither layout solves
A monorepo shows an agent every caller of user_id. It doesn't tell the agent that the team decided last week to keep user_id in the v1 API until March. Cross-team decisions live outside the code, in either layout.
Where Lockstep fits
Lockstep captures decisions like that from PRDs, Slack, and pull requests, routes each to its owner for approval, and briefs Claude Code sessions on the ones that apply to the code being changed, in one repository or many.
See how it works.
Sources checked 16 November 2026
Related reading
For instruction files in large repos, see CLAUDE.md examples. For parallel work, see Claude Code worktrees. For ownership in a monorepo, see CODEOWNERS file examples. For how to branch, see trunk-based development.
Frequently asked questions
- What is the difference between a monorepo and a polyrepo?
- A monorepo stores many projects, which may be unrelated, in one version control repository. A polyrepo, or multi-repo, setup gives each project its own repository. A monorepo isn't the same as a monolith: the projects inside it can still be built and deployed independently.
- What are the advantages of a monorepo?
- Wikipedia lists easier code reuse through shared libraries, simpler dependency management, atomic commits across projects, large-scale refactoring with the whole codebase visible, and easier collaboration across teams.
- What are the disadvantages of a monorepo?
- Loss of per-project version numbers in some setups, no per-project access control by default, which can conflict with least privilege, more storage because you check out everything, and build and version control tooling that has to scale.
- Is a monorepo better for AI coding agents?
- It can be. An agent in a monorepo can see the shared library it's calling and update every caller in one change. The risk is too much context, which Claude Code addresses with per-directory CLAUDE.md files, exclusions, read deny rules for generated code, and starting sessions in a subdirectory.
- How do I use Claude Code across multiple repositories?
- Start in one repository and grant access to others with --add-dir or the additionalDirectories setting, per Claude Code's large-codebase guide. Shared conventions across many repositories can be packaged as a plugin in an internal marketplace.
Keep reading