--- slug: codebase-map type: pattern summary: "Maintain a compact structural map of a repository so a coding agent can orient itself before reading full files." created: 2026-06-14 updated: 2026-06-14 related: context-engineering: relation: specializes note: "A Codebase Map is context engineering applied to a repository's structure." context-window: relation: depends-on note: "The map exists because full repositories rarely fit inside the active window." retrieval: relation: uses note: "A codebase map retrieves structural facts about code before the agent reads source files." progressive-disclosure: relation: implements note: "The agent sees the map first, then drills into full files only when the map says they matter." tool: relation: uses note: "Many maps are exposed as a tool the agent can query during a session." mcp: relation: uses note: "MCP is a natural way to expose a maintained code graph or repository index to multiple agents." harness-engineering: relation: used-by note: "Harnesses use codebase maps to make agents reliable on a specific repository." dependency: relation: uses note: "Dependencies are one of the relationships the map must preserve." local-reasoning: relation: supports note: "A good map tells the agent which local context is enough for the current change." blast-radius: relation: reduces note: "The map helps estimate which files, tests, and callers might be affected by a change." --- # Codebase Map > **Pattern** > > A named solution to a recurring problem. *Maintain a compact structural map of a repository so a coding agent can orient itself before reading full files.* *Also known as: Repository Map, Repo Map, Codebase Index, Code Graph, Codebase Memory.* When a human joins an old codebase, they don't start by reading every file. They scan the tree, search for names, jump to definitions, inspect callers, and build a rough mental map before making a change. A coding agent needs the same orientation, but it has a context window instead of years of project history. A Codebase Map gives the agent that first pass in a form it can use. ## Understand This First - [Context Window](context-window.md) — the bounded working memory the map is trying to protect. - [Context Engineering](context-engineering.md) — the broader discipline this pattern belongs to. - [Retrieval](retrieval.md) — the query-time pull that brings selected map facts into context. - [Module](module.md) — the code structure a useful map has to expose. ## Context At the **agentic** level, a Codebase Map is the repository's orientation layer for a coding agent. It is a compact, maintained representation of files, symbols, definitions, call relationships, dependencies, tests, and other facts that help the agent decide where to look next. The map is not the source code. It is a wayfinder. It may be generated from an abstract syntax tree (AST), language-server data, search indexes, embeddings, git history, ownership metadata, or a precise code graph. The implementation varies, but the purpose does not: give the agent enough structure to choose its next read without stuffing the whole repository into the [context window](context-window.md). This pattern matters most in brownfield work. A small greenfield script can fit in a prompt. A mature service, library, mobile app, or monorepo can't. The agent has to learn where the relevant code lives, which modules call it, which tests guard it, and which neighboring abstractions will object if it makes the easy change. ## Problem How do you help a coding agent understand a repository's structure before it knows which files matter? The naive options both fail. Sending the whole repository wastes the window and often exceeds it. Asking the agent to discover everything from `grep`, `find`, and repeated file reads works, but it burns tokens and repeats work every session. It also misses relationships that aren't obvious from text search alone. The result is familiar: the agent edits the obvious file and ignores the helper one directory over. It misses the test fixture that encodes the invariant, or changes an interface without noticing its callers. It didn't lack intelligence. It lacked a map. ## Forces - **Context is finite.** Full files are expensive, and most of their lines are irrelevant to the current task. - **Structure beats keyword matches.** A symbol's callers, implementers, tests, and boundaries often matter more than the file where a word appears. - **Freshness matters.** A stale map is worse than no map because it gives the agent confidence about code that has moved. - **Precision has a cost.** ASTs, language servers, and precise code graphs are richer than plain text indexes, but they're harder to build and maintain. - **Security still applies.** A shared index must prove the agent can see a file before returning facts about it. ## Solution **Maintain a compact, queryable map of the codebase and teach the agent to use it before reading source files.** The map should answer orientation questions cheaply. What files exist? What symbols do they define? Who calls what? Where do tests live? What depends on this module? Which files usually change together? Build the map from source-controlled facts whenever possible. Parse files with tree-sitter, a language server, or a precise indexing format. Add text and embedding search where structure is not enough. Include signatures and short definitions, not whole implementations. Preserve relationships: imports, call sites, inheritance, generated artifacts, test targets, ownership, and public APIs. Expose the map through the harness. A simple agent can receive a small repo-map excerpt at the start of each task. A richer harness can provide `find_symbol`, `list_callers`, `related_tests`, `impact_radius`, or `search_codebase` tools. A team-scale system can serve the map through [MCP](mcp.md) so every agent uses the same maintained index. Use the map for [progressive disclosure](progressive-disclosure.md). The agent starts with orientation, then drills down: 1. Read the task. 2. Query the map for likely files, symbols, callers, and tests. 3. Read the smallest full files that matter. 4. Make the change. 5. Use the map again to check affected callers and tests. The map routes attention. It doesn't replace the source files, tests, or build. Those remain the [source of truth](source-of-truth.md). If the map and source disagree, trust the source and rebuild the map. > **⚠️ Warning** > > Don't let a codebase map become an unsourced memory dump. Every fact in it should either be regenerated from the repository or carry enough provenance that the agent can verify it. A stale map can send an agent confidently into the wrong module. ## How It Plays Out A developer asks an agent to add a retry policy to a payments service. Without a map, the agent searches for "retry," opens five files, and edits the first client wrapper it finds. With a map, it sees that `PaymentGateway` has three implementations, `StripeGateway` and `AdyenGateway` share a `GatewayRequest` adapter, and `tests/payments/test_gateway_retries.py` is the caller-facing contract. It reads two files and one test instead of a dozen loose matches. A platform team exposes its internal code graph through an MCP server. When an agent is asked to rename a public method, it first asks for callers, downstream services, and related tests. The map shows that two batch jobs call the method indirectly through a generated client. The agent includes those jobs in its plan before it edits anything, so review starts with the real blast radius instead of discovering it after CI fails. A startup tries to save time by giving agents a hand-written markdown map of the repository. It works for a week. Then the auth module is split, a background worker moves, and the map is no longer true. The next agent follows the old path and patches a dead adapter. The team replaces the hand-written map with a generated one, stamps it with the commit it was built from, and teaches the harness to rebuild it whenever the checkout changes. ## Consequences **Benefits.** A Codebase Map cuts the cost of orientation. Agents spend fewer turns discovering file structure, waste fewer tokens on irrelevant files, and make better first plans because they can see relationships before reading implementations. It also improves review quality: when the agent names the callers, tests, and dependency edges it used, the human reviewer can check whether the claimed scope matches the codebase. **Liabilities.** The map becomes another maintained artifact. If it is slow to build, people won't refresh it. If it is too coarse, it becomes a dressed-up file list. If it is too detailed, it competes with the source code for context budget. If access control is weak, a shared index can leak filenames, symbols, or relationships the agent shouldn't see. Treat the map as infrastructure, not documentation. Generate it, cache it, age it out, and make its provenance visible. When you're working in a small repo, a lightweight symbol map may be enough. Across a monorepo or an organization, the map starts to look like codebase search infrastructure. It needs precise indexes, incremental updates, proof of access, and query tools the agent can call without rebuilding the world every session. ## Sources - Aider's *[Repository map](https://aider.chat/docs/repomap.html)* documentation and Paul Gauthier's *[Building a better repository map with tree sitter](https://aider.chat/2023/10/22/repomap.html)* are the clearest early practitioner account of sending a compact repository map to a coding model: files, important symbols, signatures, and graph-ranked relevance under a token budget. - Martin Vogel, Falk Meyer-Eschenbach, Severin Kohler, Elias Grunewald, and Felix Balzer formalized the persistent graph version in *[Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP](https://arxiv.org/abs/2603.27277)* (2026), evaluating a tree-sitter knowledge graph exposed through MCP across 31 repositories. - Jeremy Stribling's Cursor essay *[Securely indexing large codebases](https://cursor.com/blog/secure-codebase-indexing)* describes the production editor version: incremental semantic indexing, Merkle-tree synchronization, cached embeddings, and proof-of-access checks for reused team indexes. - Sourcegraph's *[AI coding context tools compared](https://sourcegraph.com/resources/context-compare)* frames the organization-scale version: persistent code graphs, precise indexing, cross-repository navigation, and MCP-exposed code intelligence for agents. --- - [Next: Reference Repository](reference-repository.md) - [Previous: Context Engineering](context-engineering.md)