Big repo, small context: how agents read your code

A digest of every tracked file in this site's repository works out to about 1.3 million characters, call it 324,000 tokens at the usual four-characters-per-token estimate. That does not fit the default 200,000-token context window at all, let alone leave room to work. Every tool that runs an agent against a big codebase solves this problem before the first prompt, and the solutions group into four families: instructions that ride along, maps of the code, retrieval on demand, and state that survives the session.

What does a fresh session actually pay?#

The arithmetic on this repository, measured today: 258 tracked files excluding the lockfile, 99 of them source code worth roughly 105,000 tokens, 74 of them blog content worth roughly 129,000. The words outweigh the code, which surprised me too.

Sending the whole digest as fresh input at Claude Opus 5.5 list prices would cost about $1.30 per session start, 324,000 tokens at $4 per million. The same tokens as a cached read cost about six cents at $0.20 per million, and the cache is the bill for running agents. That article covers making the repeated prefix cheap. This one is about the other half: sending less in the first place, because no cache helps when the window itself is too small.

The cheapest correct answer for a task is usually a small subset. The blog workflow on this site needs the style guide, the category list and the last two articles, about 21,600 characters or 5,400 tokens. That is one sixtieth of the digest, about two cents as fresh input, and it fits in the first message.

The map file rides along with every session#

An AGENTS.md or CLAUDE.md file is the smallest of the four families and the first one to implement. Claude Code loads it at session start as persistent context, alongside auto-generated memory notes, and re-injects it from disk after every compaction (memory docs). The agents.md format calls itself "a README for agents" and counts more than 60,000 open-source projects using it. It grew out of a working group across OpenAI, Google, Cursor and others, and it supports one file per package, with the nearest file winning. OpenAI's own repository carried 88 of them at the time the format's site counted.

This repository has one, and I did not write it. It is 678 bytes, about 170 tokens, and next dev writes and re-adds it itself, warning every agent that this Next.js version has breaking changes and pointing at the bundled docs. The framework now maintains agent context for its own ecosystem, which is a strong vote on where the industry thinks this belongs. The docs also recommend keeping these files under 200 lines, because length costs both adherence and context on every message.

Maps, indexes and symbols#

Aider's repo map is the classic construction. Tree-sitter parses each file into a syntax tree, definitions and references get extracted, and a graph ranking algorithm treats files as nodes and dependencies as edges to pick the most-referenced identifiers (aider's construction post). The result is a skeletal map of the whole repository, signatures without bodies, sized to a token budget that defaults to a thousand tokens and adapts to the state of the chat (docs). The model reads the map, decides which files matter for the task, and only those enter the context.

Cursor builds an index. Each file splits into syntactic chunks, the chunks become embeddings, and a Merkle tree of file hashes lets the index sync only what changed, with embeddings cached by chunk content (Cursor's engineering post). Their evaluation puts semantic search at a 12.5 percent average accuracy improvement, and the same post shows why the index has to be shared: clones of one codebase inside an organization are 92 percent similar, and reusing a teammate's index cuts the 99th-percentile time to first query from 4 hours to 21 seconds.

Serena takes the third road: it gives the agent the Language Server Protocol over MCP, 40-plus languages, symbol-level operations like find symbol, find references and replace symbol body (oraios/serena). An agent quoted in their evaluation describes the effect on cross-file renames and reference lookups, procedures it counts at eight to twelve careful error-prone steps in raw form: they "collapse into one atomic call".

The digest row calls for caution. Repomix packs a codebase into AI-friendly formats, and for a one-time review of something small that is exactly right. As a habit on a growing repository it re-pays the full window on every session, the very cost the other four rows are designed to avoid.

What compaction keeps and what it risks#

Long sessions do not fit either, so Claude Code compacts automatically near the limit: the conversation becomes a structured summary, project instructions and memory re-inject from disk, and up to five recently touched files come back, with anything over 5,000 tokens returning as a bare path reference without its content (context window docs). Subagents solve the same pressure from the other side by reading large files in their own window and returning only the summary.

The summary that compaction produces is state the model wrote and later trusts as its own context, and that channel has a documented failure mode: OpenAI's misalignment reports caught models smuggling instructions through exactly this route, summaries instructing later instances to conceal mistakes. The write-up of those reports covers the mechanics; the practical rule is to treat what the model writes for itself with the same suspicion as tool output. Keeping durable state in your own files, the map file and the codebase, keeps the summary small and less load-bearing.

The walkthrough on this repository#

The blog workflow here is the measured example. A new article needs docs/blog-style.md, src/content/categories.json and the two most recent articles: 5,400 tokens of context, a map file of 170, an AGENTS.md the framework maintains for free, and no digest anywhere. A repository-level map or index would earn its keep the day a task stops being localized, a cross-cutting rename, an architecture question, and the table above says which to reach for.

The pattern generalizes beyond code. What repeats belongs in a stable prefix, instructions, conventions, schemas, because that is what caches well. What varies belongs in retrieval, maps, indexes, symbol tools, because that is what keeps the window small enough to think in. The agents that feel fast on a big codebase are not reading faster. They are reading less, and the four families above are the entire playbook for arranging that.