lockstep
3 min readNaman Jain

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

MonorepoPolyrepo
Cross-project changeOne atomic commitCoordinated changes and versions
Code reuseShared libraries, used directlyPublished packages, versioned
RefactoringSee and fix every callerCallers live elsewhere
Access controlRead access to everything by defaultPer repository, least privilege
VersioningOften one version for allPer project
Checkout and storageEverything by defaultOnly what you need
ToolingNeeds build tools that scaleSimpler 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:

ProblemClaude Code feature
One root file can't cover every packagePer-directory CLAUDE.md files, loaded for the code you touch
Packages you never work inclaudeMdExcludes
Generated and vendored codeRead deny rules in permissions.deny
Scanning files to find symbolsA code intelligence plugin
Worktrees with the whole repoworktree.sparsePaths
Work scoped to one packageStart 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

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