AI Agents in a Monorepo: Working With Large Legacy Codebases

A coding agent that writes a clean feature in a fresh repo can flounder in a five-year-old monorepo with a thousand interdependent files. The reason is simple: the agent cannot fit the whole codebase in its head, and a large legacy system is precisely where context is everything. Getting useful work out of AI agents in big repositories is less about raw model power and more about how the codebase is indexed, what the agent is told, and how the monorepo's own tooling is exposed to it.

This deep dive covers the four levers that decide whether an agent helps or harms in a large codebase: context windows, indexing, convention files, and monorepo tooling.

Context windows are big — and not the answer

Modern models carry enormous context. Per Anthropic's documentation, Claude Opus 4.8 and Sonnet 4.6 offer a 1 million-token context window, up from the 200K of earlier models; the 1M window first launched for Claude Sonnet 4 on 12 August 2025, framed as processing codebases of 75,000+ lines in a single request. Google's Gemini 2.5 Pro also reaches 1 million tokens, and the GPT-5 family ranges from roughly 400K upward.

But more window is not the fix it appears to be. Anthropic warns of "context rot": accuracy and recall degrade as the token count grows, so curation matters more than raw capacity. Dumping an entire monorepo into the prompt is both expensive and counterproductive — the agent loses the signal in the noise. The practical lesson is that large repos are handled by retrieving the right context, not loading all of it.

Indexing: how agents find the right files

This is where the real engineering lives. Rather than reading everything, agents index the repository and retrieve only relevant chunks:

• Cursor builds a Merkle tree of file and folder hashes to detect changes, splits changed files into syntactic chunks, embeds them, and stores the embeddings in a remote vector database — without keeping raw source server-side.
• GitHub Copilot shipped semantic code-search indexing to general availability on 12 March 2025; it indexes in seconds, triggers automatically when Copilot Chat opens, and is available on all tiers with no repo-size limit.
• Aider takes a different, embedding-free route: it parses the repo with tree-sitter across 100+ languages, builds a reference graph, and ranks key identifiers with NetworkX PageRank into a token-budgeted "repo map."

Each approach answers the same question — which slice of this large codebase does the agent need right now? — and the answer is retrieval, not brute force.

Convention files: the README for agents

A large legacy repo carries implicit knowledge — build commands, test runners, naming rules — that an agent cannot infer reliably. Convention files encode it explicitly.

AGENTS.md has become a de facto open standard — a "README for agents" used by over 60,000 open-source projects and now stewarded by the Agentic AI Foundation under the Linux Foundation. It is plain Markdown with no schema, giving any agent the build and test commands plus conventions in one predictable place. Claude Code is the notable exception: it reads CLAUDE.md, loaded into context at the start of every session, with a recommended size under about 200 lines and a load order that walks up the directory tree — which makes it well-suited to monorepos where rules differ per package. (Claude Code can bridge to AGENTS.md via an import.)

Monorepo tooling the agent can call

The monorepo's own tools are the agent's map. Nx ships an MCP server and agent skills: its nx-workspace skill teaches an agent to explore via nx show projects and nx graph, find affected projects, and trace the project graph, and npx nx configure-ai-agents wires up MCP, skills and convention files across Claude Code, Cursor, Copilot, Gemini and Codex at once. The repo-size spectrum runs from Turborepo (Vercel, JS/TS monorepos with caching) up to Bazel (Google, open source, built for billions of lines with hermetic builds and remote execution). An agent that can query the project graph navigates a large repo far more reliably than one grepping blindly.

How good are agents on real code?

The benchmark to watch is SWE-bench Verified: 500 human-validated real GitHub issues, a subset of SWE-bench's 2,294, released by OpenAI and Princeton authors on 13 August 2024 and screened by contracted developers for unambiguous problems and fair tests. The model must produce a patch that passes hidden unit tests — a realistic proxy for fixing a real bug in a real repo.

Top scores have climbed steeply. Claude Opus 4.8 reached 88.6% on SWE-bench Verified (released 28 May 2026), and Anthropic's headline metric has shifted to the harder SWE-bench Pro (69.2% for Opus 4.8) because Verified "is approaching saturation." OpenAI likewise stated in early 2026 that Verified "no longer measures frontier coding capabilities." The takeaway is double-edged: agents are genuinely strong on self-contained, well-tested issues, but a saturating benchmark says little about the messy cross-file refactors and undocumented legacy patterns that define real monorepo work.

FAQ

Won't a 1M-token context window just solve large-codebase problems? No. Anthropic's own "context rot" caveat means accuracy drops as the window fills. Large repos are handled by retrieving relevant context through indexing, not by loading everything.

Should I use AGENTS.md or CLAUDE.md? Use AGENTS.md as the cross-tool standard (60k+ projects, Linux Foundation-stewarded). If you use Claude Code, also provide CLAUDE.md, since that is the file it reads; it can import AGENTS.md to avoid duplication.

How do agents avoid reading the whole repo? Through indexing and retrieval: Cursor uses a Merkle tree plus chunk embeddings, Copilot a server-side semantic index, and Aider a tree-sitter repo map ranked by PageRank. Each retrieves only the relevant slice.

Do high SWE-bench scores mean agents handle legacy code well? Not directly. SWE-bench Verified is self-contained, well-tested issues and is now saturating. Real monorepo work — cross-cutting refactors, undocumented conventions — is harder than the benchmark measures.

Bottom line

Working AI agents into a large legacy monorepo is a context-engineering problem, not a model-size problem. Lean on indexing and retrieval over giant prompts (context rot is real), encode the repo's implicit knowledge in AGENTS.md or CLAUDE.md, and expose the monorepo's own tooling — Nx's project graph, Turborepo, Bazel — so the agent can navigate. SWE-bench scores near 88% show the ceiling is rising fast, but the gap between a clean benchmark issue and a tangled legacy refactor is exactly where your conventions and tooling earn their keep.

Sources and further reading