A monorepo keeps many projects in one repository, while a polyrepo splits them across separate repositories. With modern build tooling, the technical challenges of maintaining a large repository are solvable, so the choice is mostly organizational: how your teams want to share code, review changes, and release.
Monorepo vs polyrepo at a glance
Section titled “Monorepo vs polyrepo at a glance”Monorepos optimize for atomic changes and shared tooling, while polyrepos optimize for team isolation.
| Dimension | Monorepo | Polyrepo |
|---|---|---|
| Code sharing | Import shared code directly from the same repository | Publish shared code as versioned packages |
| Atomic changes | One PR can update an API and every consumer | Cross-project changes span multiple PRs and releases |
| Release cadence | Projects build together, artifacts deploy on any schedule | Independent by default, each repository on its own |
| CI cost | One pipeline that needs tooling to run only what changed | Many small pipelines, each maintained separately |
| Access control | Everyone sees all code, with per-folder ownership rules | Repository-level permissions per team |
| Dependency versions | A single version policy is enforceable, but optional | A single policy can't be enforced, versions drift |
| Team autonomy | Teams follow shared conventions | Each team picks its own workflow, conventions, and release cadence |
A monorepo doesn't force everything to release together. Projects build from the same commit, but each build artifact or Docker image carries its own tag, and teams control when a tag reaches production. What a monorepo does force is that every project builds against the latest shared code, so projects stay current with each other - an advantage or a burden depending on what your teams need. A polyrepo makes independent cadences the default because everything is already split.
When should you choose a polyrepo?
Section titled “When should you choose a polyrepo?”Choose a polyrepo when strict repository-level access control is a hard requirement, or when teams share little code and nothing should force them to move together.
The cost is that sharing code becomes harder and every maintenance task, from dependency upgrades to CI changes, has to be repeated across all the repositories in the organization.
Can AI agents work across polyrepos?
Section titled “Can AI agents work across polyrepos?”AI agents can work across polyrepos, but an agent working in one repository can't see the consumers of the code it's changing, so cross-repository changes need extra coordination. Agents work best when they can see every project affected by a change, which a monorepo gives them by default. Meta-harnesses like Polygraph, from the Nx team, give AI agents cross-repository context in polyrepo setups.
Organizational decisions
Section titled “Organizational decisions”For teams to work together in a monorepo, they need to agree on how that repository is going to be managed. These questions can be answered in many different ways, but if the developers in the repository can't agree on the answers, then they'll need to work in separate repositories.
- Dependency Management - Should there be an enforced single version policy or should each project maintain their own dependency versions independently?
- Code Ownership - What is the code review process? Who is responsible for reviewing changes to each portion of the repository?
- Project Dependency Rules - What are the restrictions on dependencies between projects? Which projects can depend on which other projects?
- Folder Structure - What is the folder structure and naming convention for projects in the repository?
- Git Workflow - What Git workflow should be used? Will you use trunk-based development or long running feature branches?
- CI Pipeline - How is the CI pipeline managed? Who is responsible for maintaining it?
- Deployment - How are deployments managed? Does each project deploy independently or do they all deploy at once?
How many repositories?
Section titled “How many repositories?”Once you have a good understanding of where people stand on these questions, you'll need to choose between one of the following setups:
One monorepo to rule them all
Section titled “One monorepo to rule them all”If everyone can agree on how to run the repository, a single monorepo provides the most benefit. Every project can share code, and maintenance tasks and anything else that needs coordination can be performed in one PR for the entire organization.
Nx addresses the technical challenges of a repository this size, so the limiting factors in how large it grows are organizational rather than technical. Once the repository scales to hundreds of developers, you need to take proactive steps to ensure that your decisions about code review and project dependency restrictions do not inhibit the velocity of your teams. Also, any shared code and tooling (like the CI pipeline or a shared component library) need to be maintained by a dedicated team to help everyone in the monorepo.
Polyrepos - a repository for each project
Section titled “Polyrepos - a repository for each project”If every project is placed in its own repository, each team can make their own organizational decisions without the need to consult with other teams. Unfortunately, this also means that each team has to make their own organizational decisions instead of focusing on feature work that provides business value.
Nx can still be useful with this organizational structure. Tooling and maintenance tasks can be centralized through shared Nx plugins that each repository can opt-in to using. Since creating repositories is a frequent occurrence in this scenario, Nx generators can be used to quickly scaffold out the repository with reasonable tooling defaults.
Polyrepos also fragment the context AI agents work with. The Polygraph meta-harness addresses this by linking your repositories into a synthetic monorepo, so one agent session works across all of them with shared context and coordinated changes.
Multiple monorepos
Section titled “Multiple monorepos”Somewhere between the single monorepo and the full polyrepo solutions exists the multiple monorepo setup. The split usually follows a real boundary: an internal codebase next to a public open source one, product lines in different domains that share no code, or groups of teams that answer the organizational questions above differently. Each monorepo is configured in the way that best suits the teams working in it.
Compared to a single monorepo, this setup adds overhead: multiple CI pipelines and repeated tooling maintenance. In exchange, each team works in a repository optimized for how they work.
Polygraph helps with the multiple monorepo setup by linking the repositories and treating them as one, so work and AI agent sessions can span all of them.