Repository Context for AI Agents, Explained
"Give the agent more context" is the most common advice for AI coding, and the vaguest. This article breaks down what repository context actually is, why pasting files or relying on a bigger context window isn't enough, and how to give an agent the context it needs.
What "repository context" means
Code is only one layer. An agent making a good change needs several:
| Layer | Question it answers |
|---|---|
| Code | What does this function do? |
| Structure | Which modules and files make up this area? |
| Relationships | What depends on this, and what does it depend on? |
| Features | Which code implements a given product behaviour? |
| Data | Which tables or collections does this read or write? |
| History | When and why did this change? |
| Organisation | Which other repositories are involved? |
Most agents start with only the first layer, plus whatever files they happen to open.
Why a bigger context window isn't the answer
Even with a large context window, two problems remain:
- The agent has to find the right files first. Context only helps if it's relevant. In a large codebase, much of an agent's effort goes into searching rather than reasoning.
- Relationships aren't written down in any one file. "Service A calls service B" might only exist as an HTTP call to a URL. Reading more files doesn't automatically reveal that.
So good context is less about more text and more about the right structure, prepared in advance.
Local context vs indexed context
There are two sources of repository context:
- Local working tree
- what's on your machine right now, including your branch and uncommitted changes. It's the most current, but limited to what you've cloned.
- Organisation index
- a pre-built view of all your organisation's repositories. It's broader, but reflects the indexed state.
The best results combine both: local first where it exists, the index for everything else.
How CodeZero provides repository context
CodeZero builds and maintains these layers, so they don't have to be rebuilt for every task:
- Code Graph: an organisation-wide view of how modules, files, data and repositories connect.
- Feature Mapping: traces one product feature from where it starts, through the files involved, to the data it reads or writes and any other repository it depends on.
- Git Tree: repository history and everyday Git operations.
- Context-aware chat: ask questions answered from all of the above.
- Local first: where a repository is checked out, CodeZero prefers your working tree. Otherwise it uses the organisation index, read-only.
CodeZero runs inside VS Code alongside your coding agent. It supplies the context, and your agent writes the code.
FAQ
Is repository context the same as RAG?
Partly. Search-based retrieval finds similar text. Repository context also includes structure and relationships, such as what depends on what, which text similarity doesn't capture.
Does indexed context include uncommitted changes?
The organisation index reflects indexed code. Uncommitted changes come from your local working tree, which CodeZero prefers when a checkout exists.