AI coding agents don't load an entire codebase into context. They start from a cheap map of the file structure, then selectively fetch specific files using tools like grep and glob based on the task at hand — treating context as a limited resource to spend deliberately, not a cache to fill upfront.
Key takeaways
- Map first, read second. A file-tree map costs very few tokens; full file contents are fetched only as needed.
- Two channels exist: preloaded and on-demand. Project instruction files load automatically; almost everything else is fetched during the task.
- Search tools (grep/glob) do the real navigation. They let an agent find relevant code without knowing the codebase's layout in advance.
- MCP extends the same principle outward — external tools and data fetched on demand rather than pushed into every prompt.
- Wrong-file mistakes come from inference, not malfunction. Selection is based on naming and search matches, not true architectural understanding.
Why agents don't just read everything
Context windows are finite, and every token spent on an irrelevant file is a token not available for the actual task, plus added noise that can degrade the quality of what the model produces. For anything beyond a small project, preloading the full codebase is both impractical and counterproductive — the agent would spend more of its attention filtering noise than solving the problem.
This is the same resource-scarcity logic that shows up everywhere else in engineering: bandwidth, memory, crawl budget. Treating context as scarce rather than abundant is the design decision that makes agents usable on real, large codebases instead of toy examples.
- Context window
- The total amount of text — measured in tokens — a model can consider at once, including the conversation so far, any loaded files, and the instructions guiding it. Everything an agent reads competes for space in the same fixed budget, which is why selective reading matters more as a codebase grows.
Two channels: what's preloaded versus what's fetched
Most agent architectures split file awareness into two distinct mechanisms.
| Mechanism | When it loads | Typical content |
|---|---|---|
| Preloaded instructions | Automatically, before the task starts | Project-level conventions — e.g. a CLAUDE.md or AGENTS.md file |
| On-demand retrieval | During the task, as the agent decides it's needed | Specific source files, found via search tools |
| External tools/data (MCP) | On demand, when the task requires outside information | APIs, databases, documentation not present in the repo at all |
The preloaded layer is deliberately small and stable — it's meant to set conventions and context that apply to nearly every task, so loading it automatically is worth the token cost every time. Everything else is too variable and too large to preload safely, so it moves into the on-demand layer instead.
How the on-demand layer actually navigates
Search primitives — typically grep for text matching and glob for filename patterns — let an agent find relevant code without already knowing the codebase's structure. This mirrors how an experienced engineer actually works in an unfamiliar repository: search for the function name, follow the imports, narrow in, rather than reading every file top to bottom.
The Model Context Protocol extends the identical principle beyond the filesystem: instead of having every possible external tool or data source pushed into the prompt just in case, MCP lets an agent fetch a database record, an API response, or a piece of documentation only when the task actually calls for it. Different mechanism, same underlying discipline — context spent deliberately rather than reserved speculatively.
Why agents sometimes read the wrong file
File selection is inferred from naming conventions, directory structure and search-term matches — not from genuine understanding of the codebase's architecture. Ambiguous file names, duplicated logic living in two places, or a search term that happens to match an unrelated file can all send an agent to the wrong location, even when its eventual output still looks plausible.
This is worth knowing precisely because the failure mode is quiet. A model working from the wrong file doesn't usually announce that it's confused — it produces a confident, coherent answer grounded in the wrong context. Reviewing what an agent actually read, not just what it produced, remains a genuinely useful habit even as these tools get more capable.
The short version
Coding agents navigate codebases the way a competent engineer new to a repository does: a quick map, then targeted searches, then reading exactly what the search points to. That design is what makes them workable on large, real projects — and understanding it explains both their genuine competence and the specific, quiet way they occasionally get it wrong.