When you ask an AI coding agent to work on your project, the model does not have your entire codebase in its head. It has a context window, which is the fixed amount of text it can process in one go. For coding agents, that window is the budget for everything: your prompt, the files the agent reads, the agent's own reasoning, and the response it produces.
Why Context Windows Matter
A typical coding agent context window ranges from 32,000 to 200,000 tokens. A token is roughly a word fragment. In practice, a large file might be a few thousand tokens, and a medium-sized codebase is hundreds of thousands of tokens.
That means the agent cannot load everything at once. It has to pick. If it picks the wrong files, it will make mistakes. If it picks the right files but misses a subtle interaction, it will still make mistakes.
Context windows are measured in tokens, not lines. A file with lots of comments or long string literals consumes more tokens than a file with compact code. Be aware of what you are loading.
How Agents Cope
Agents use several strategies to fit within the window:
- File selection. They read only the files that seem relevant to the task.
- Summarization. They condense long files into shorter notes.
- Iterative reading. They read a file, decide what to do, then read another file.
- Context files. They load a project conventions file that gives high-level guidance without reading every file.
Each strategy trades completeness for capacity. The agent is constantly deciding what to keep and what to ignore.
What This Means for Your Project
You can make the agent more effective by reducing what it has to load:
- Keep files focused. A 5,000-line file is harder to load than five 1,000-line files.
- Use clear names. The agent searches by name and keyword.
-
Provide a map. A
CONTEXT.mdor architecture note gives the agent the big picture without reading the whole repo. - Scope your requests. "Update the auth middleware" is easier than "fix the app."
A common failure mode is asking the agent to refactor a feature that touches files across the project without giving it any hints. The agent loads what it can find, misses a critical dependency, and produces a partial fix.
Local Models and Context
Local models often have smaller context windows than cloud models. If you run OpenCode against a local 14B model, you might have 32K tokens to work with. That is enough for a single-file task or a small refactor, but not for a large cross-file change. Plan local-model tasks accordingly.
Originally published at pickuma.com. Subscribe to the RSS or follow @pickuma.bsky.social for new reviews.
Top comments (0)