Monorepo vs Polyrepo Tradeoffs for AI Agent Workflows

The arrival of AI coding agents as genuine software producers changed the variables that decide repository structure. Agents now read a codebase, reason about it, edit files across many locations, run tests, and open pull requests with minimal supervision. The work unit is no longer a human writing a patch. This is a structural forcing function.

The constraints that made a repository model good or bad for human workflows are not the same constraints that make it good or bad for agent workflows. The old tradeoffs, ownership boundaries, deployment cadence, blast-radius isolation, were real, and both camps were right under human-centered conditions. But the optimization function has shifted, and a question that felt settled for many organizations is live again.

What each structure actually buys you before agents enter the picture

Both repository models offer real, legitimate advantages, and neither is wrong in isolation. Acknowledging this honestly is the precondition for making a credible claim about which one agents favor. A monorepo's core offer is atomic cross-project changes, unified dependency versions, and, most consequentially for what follows, a build graph that exists by construction as a queryable artifact. The atomic cross-project change is the strongest monorepo argument: one commit, one review, one revert path when an API contract and all its clients live together. The build system becomes infrastructure. Past a certain size, change detection, remote caching, and a team that owns the machinery are mandatory, not optional.

A polyrepo's core offer is autonomy, isolated CI pipelines, independent release cadence, and a clean ownership boundary that maps onto a team. The variance that monorepos can exhibit at the 90th percentile is a genuine cost. There the polyrepo cost appears too: everything cross-cutting gets harder, and standardizing security scanning, CI conventions, or dependency policy across many repos is a campaign rather than a commit.

The thing the standard pros-and-cons lists file under "harder dependency management" and move past in a sentence deserves more attention. In a polyrepo, nobody can answer "what depends on this" without going looking. That unresolved question is the real variable the debate never surfaces.

Why dependency graph queryability, not co-location, is the deciding variable

The real question is not where code lives but whether the dependency graph is declared to a machine. A monorepo's build system produces a queryable graph as a by-product of the architecture. A polyrepo leaves the same graph implicit and scattered across manifests no single tool reads.

The debate is argued as a code-location debate, but the variable underneath, the one that decides whether teams ship confidently or play dependency archaeology, is queryability of the graph. Infrastructure never got a vote. In a monorepo with a real build graph, an agent calls a query and gets blast radius in a single tool call. In a polyrepo, the same graph is implicit: it exists in the relationships between packages and manifests, but no single tool reads it, and the agent must either reconstruct it at query time or operate blind.

This is not a claim that physical co-location is magic. It is a claim that co-location is the current reliable path to having a machine-readable graph by default, without a dedicated platform investment to produce one artificially. The objection worth addressing is that if the real variable is queryability, then a well-instrumented polyrepo is equivalent. That is technically correct but practically demanding. The investment required to reach equivalence is substantial, and most organizations do not make it.

An agent operating in a polyrepo without explicit graph visibility must either reconstruct dependencies on every task or operate blind to cross-repo blast radius. A live architecture graph that spans the entire codebase, whether monorepo or polyrepo, gives agents the visibility they need to make safe, coordinated changes across boundaries. Tools like Graphide, which convert any codebase into a live, queryable architecture graph, demonstrate how the infrastructure problem of graph queryability can be solved independent of repository structure, turning a polyrepo's implicit dependencies into something an agent can actually read and reason about.

The three walls agents hit in a polyrepo, and why the graph is behind all three

Every practical limitation agents hit in a polyrepo is a symptom of the same missing artifact: a graph the agent can read rather than reconstruct. The failures cluster into three walls. The first is read: no cross-project context. Change a UI component library and the agent has no idea which applications consume it or how they will break. With the graph, the agent understands dependencies, proposes consistent changes, and catches downstream impacts before they become bugs.

The second is write: no way to land cross-project changes atomically. A cross-cutting change in a polyrepo becomes a distributed transaction, with coordinated PRs, version bumps, release ordering, and a window where some services run the old interface while others run the new one. Every handoff back to a human for cross-repo coordination makes agents less autonomous. In a monorepo, an agent can modify 20 projects in a single PR: one review, one approval, one merge. Google's Rosie tool, operating in a monolithic repository, automatically refactors code across millions of files by sharding the change into smaller, independently tested and submitted pieces. That task would require complex cross-repo orchestration in a polyrepo.

The third is memory: repo boundaries wipe context. Nx names this the Memento Problem. Update Repo A with an agent on Monday, open Repo B on Thursday, and the agent is reconstructing intent from breadcrumbs. In a monorepo, the agent works in one continuous context, and mistakes are coherent and easier to spot. The graph is again the mechanism: the agent's memory of relationships persists because the relationships are encoded in one place.

What Block, Stripe, and Plaid show about agents operating with full graph context

Organizations that have given agents access to a full, co-located dependency graph report qualitatively different outcomes from those operating with fragmented cross-repo context, and the difference compounds at scale. Block's Yissachar Radcliffe made the agent connection explicit: agents perform well in their monorepo due to having access to so much context, and their bet on standardization has paid off as they have well-paved paths for agents to follow. Block's migration also surfaced the real cost honestly. It took longer than planned due to the difficulty of maintaining their desired developer experience, including CI scalability challenges, and projects with slow or custom builds required extensive optimization before they could be brought in. The graph advantage is not free.

Plaid's experience shows the graph's operational consequences at scale. As its monorepo grew to hundreds of commits a day, a merge queue became essential. Its Developer Efficiency team targeted five-minute median merge queue latency and pushed the median to 1.8 minutes by late August 2025. A monorepo simplifies this with one canonical set of agent instructions at the top level.

What the polyrepo ceiling looks like in practice, and when it matters less

The polyrepo ceiling is real for cross-cutting agent work but nearly invisible for agents scoped to a single service. The choice of structure is therefore not universal, and the honest answer depends on what agents are actually asked to do. For single-service tasks, polyrepo agents can match or beat monorepo performance. The context the agent needs is present in the one repo it can see, and the smaller surface area means faster cold-start indexing and tighter, more predictable review cycles. In those tasks, the agent in a polyrepo either guesses at interfaces it cannot see or generates changes that compile locally but violate a contract defined elsewhere.

There are legitimate conditions under which the polyrepo remains defensible. The graph advantage only materializes if someone maintains the build infrastructure that produces the graph. The monorepo's variance at the 90th percentile is a real operational cost that appears when build infrastructure lags repository growth.

A second-order polyrepo cost deserves attention because it is invisible in metrics. They duplicate code, defer refactors, and let inconsistencies accumulate. Nx describes this as friction that prevents work from happening at all, not just slowing it down.

How explicit graph tooling can lift the polyrepo ceiling without a migration

The polyrepo ceiling is not a permanent sentence. It is a consequence of an implicit graph, and making the graph explicit and queryable across repo boundaries restores most of what agents need without requiring co-location. What an agent needs is a dependency graph it can query rather than reconstruct. A monorepo with a real build graph provides one by construction. A polyrepo with a parsed cross-repo graph provides the equivalent. For polyrepo teams, Graphide makes the dependency graph visible and enforceable at the service level even before cross-repo federation is solved. For monorepo teams, Graphide extends the build graph with architectural enforcement: the map is not just a by-product of the build system but an explicit, versioned, CI-enforceable artifact.

Nx names this concept a "synthetic monorepo." Nx's Polygraph is an agent-agnostic meta-harness that connects all repositories, private and public, into one dependency graph without moving any code. It orchestrates PRs and CI across repos as a single change, and it records sessions so any agent on any machine can resume or build on prior work. Polygraph addresses all three walls: read through a connected graph across all repos, write through an agent that writes across every accessible repo and orchestrates the PRs as a single change, and memory through recorded sessions that eliminate the Memento Problem. The synthetic monorepo does not eliminate the value of an actual monorepo. It extends the properties to organizations that cannot consolidate.

The cross-repo resolution problem in a polyrepo without tooling is concrete. A dedicated platform investment, the kind Block describes as a constant source of CI scalability challenges during its migration, is required to maintain a federated search layer. Tooling that parses and surfaces the graph without requiring migration is a lower-cost path to the same agent-visible dependency model.

Why CI enforcement of architectural constraints is not optional in an agent-first codebase

A machine-readable dependency graph that is not enforced in CI is a description of the architecture as it was when the graph was last drawn. Agents will drift it, and nothing will catch the drift until production does. The risk is not hypothetical. An agent can restructure a service layer in minutes, long before a human architect would normally weigh in. "Vibe architecting," architecture shaped by prompts rather than deliberate design, is a real failure mode in 2026. The argument for CI enforcement is that it makes architectural constraints as binding as type constraints, not advisory.

The Stripe example is instructive on scope-bounding agent autonomy. Stripe caps CI retry rounds at 2. If an agent cannot fix a failing build in two attempts, the issue surfaces to a human engineer. The CI system is the gate, not the agent's judgment. CI enforcement is what bounds that escalation without eliminating useful automation.

How to choose: the decision framework that follows from the dependency graph thesis

The repository structure question resolves to a single prior question: is your dependency graph machine-readable by default, and if not, what is your plan to make it so? Everything else follows from the answer. If most agent tasks are cross-cutting, touching shared libraries, propagating interface changes, migrating dependencies across services, the case for a monorepo is strong, provided the team can fund the build infrastructure to maintain the graph at scale. Block's migration is the honest reference point. The investment is real and ongoing. The ceiling exists, but it may be above the work the agents are actually doing.

For teams in a polyrepo that cannot migrate, make the dependency graph explicit and queryable first, then enforce it in CI. That is the path to the properties a monorepo provides by construction, without requiring co-location. For teams already in a monorepo, the build graph the system produces by construction is necessary but not sufficient. It describes module relationships but does not enforce architectural constraints. Adding explicit graph enforcement in CI, with a tool like Graphide's gr check, closes the gap between "the graph exists" and "the graph is binding."

Spectro Cloud's experience offers a practical entry point for teams evaluating a greenfield decision. The AGENTS.md pattern scales in a monorepo as a thin root file plus rich per-package files. In a polyrepo, the equivalent requires per-repo maintenance that drifts without enforcement.

The conclusion that ties it together: monorepos win when the build graph is there by default. Polyrepos can match the outcome when the graph is built explicitly. The question is always whether the graph exists, not where the files live.