Giving AI Coding Agents Real Codebase Context

Codebase context for AI agents is a queryable index of a repository (its structure, dependencies, history, owners and risk) that an agent asks for through tools, one question at a time, instead of receiving files pasted into its prompt. repowise builds that index once and serves it over the Model Context Protocol through ten task-shaped tools. In a real agent loop on django/django, that cut output tokens 31.6% against a bare agent, and the agent reached its answer in 3.8 tool calls.

Part of the AI Context & MCP guide.

What is codebase context for AI agents?

Codebase context is whatever an agent knows about your repository beyond the file it has open. A bare agent builds it the slow way: it greps, opens files, and keeps what it finds in its window. An agent with an index asks instead: "what breaks if I change this?", "where does this request get validated?", "why is this written this way?". Each question returns a short, cited answer.

The window is not the constraint. The constraint is that the facts an agent needs most (who depends on a file, how often it breaks, which decision shaped it) are not in the text of the file at all. They live in the dependency graph and in git history.

One index, ten tools

repowise indexes a repository once: it parses source into AST-backed entities across 28 languages, mines git history for churn and ownership, resolves cross-file dependencies, and writes a wiki on top. repowise init registers the MCP server with Claude Code, and repowise init --codex writes project-local Codex config. Any other MCP client can start the server with repowise mcp.

repowise wiki for the repowise repository, with a page tree on the left and an architecture overview page

The agent never reads the index directly. It calls one of 10 tools, each shaped around a question, and gets back just enough: a triage card, a risk summary, one verified function body.

Task-shaped tools move orientation work out of the prompt and into the index. A generic search tool makes the agent triage results itself. get_risk returns churn, owners and blast radius in one call. The full argument reference is in the MCP tools documentation.

What does an agent call look like?

An agent asking a how-question makes one get_answer call and gets prose with citations and two quality fields, confidence (how good the prose is) and retrieval_quality (how good the evidence is). The same question in the product chat shows the shape of the answer:

repowise chat answering how a file code health score is calculated, with a seven-step activity trace and a numbered explanation

For a change, the agent asks get_risk before editing a widely imported file and get_change_risk before committing a multi-file diff. For a pattern it is about to break, it asks get_why. That sequence is the one a senior engineer follows by habit: check the blast radius, then check why the code looks that way, then edit.

Why does structured context beat prompt-stuffing?

Prompt-stuffing means pasting files until the answer is probably in the window. It fails in three ways, and a longer window fixes none of them.

• It is wasteful. Most of a stuffed prompt is imports, boilerplate and comments unrelated to the task, and the model pays latency and cost to read them.
• It degrades recall. Detail buried in the middle of a long context is easier for a model to miss; research on long contexts found accuracy drops when the relevant passage is not at the start or end.
• It hides the signal. A file does not say that it is a churn hotspot, that three packages import its exports, or that it was last changed to fix a race condition. That knowledge is in the graph and the history.

We measured what the alternative buys. The run used Codex on django/django, 43 paired questions, against a bare-agent control (August 2026):

Every question in django's question set, six arms, byte-identical prompts, each tool's full advertised surface, and a freshly built index on the same pinned commit. Every tool was called on every question, so this is like for like.

Codex (gpt-5.6-sol) on django/django at one pinned commit. Correcting for testing five tools at once, three reductions are solid and two are marginal. 5 of the 48 questions are missing from every arm equally because the run hit an API usage cap, so the figures are over the 43 questions all six arms completed; because all arms lost the same 5, the paired comparisons are unaffected.

Fewer output tokens and fewer tool calls mean the agent holds the whole task in view and reaches an answer sooner. The result is for one repository, one commit and single-session questions, and the full method is on the benchmarks page.

How does an agent know the context is current?

Every tool response carries a _meta envelope. indexed_commit and live_head say which commit the answer describes and whether HEAD has moved. A stale_warning appears only when the index is behind in a way that changed the files served, or when a served file has uncommitted edits. Its absence means current.

Responses marked complete were verified against the live file, so the agent does not re-read them. When the working tree has edits, repowise update --working-tree refreshes the index for them, and repowise update re-indexes incrementally, reprocessing changed files rather than the whole repository.

Where does the index run?

Indexing builds the structural layer (graph, git history, health, dead code) with no LLM and no API key. Generated prose uses a model provider you configure, or a local model for fully offline use. repowise is open source under AGPL-3.0 and self-hostable, so your source and the intelligence built from it stay on your infrastructure. The hosted app is free for two public repositories, with private repositories on Pro.

Set it up

pip install repowise
cd your-repo
repowise init          # builds the index and registers the MCP server with Claude Code
repowise init --codex  # also writes project-local Codex config and hooks

For other clients, add repowise mcp as a stdio server. Setup walkthroughs for each editor:

• Set up an MCP server for Claude Code, Cursor and Cline
• Claude Code context for large codebases
• Cursor codebase context via MCP
• What is MCP?, the protocol underneath
• Give your agent context without prompt-stuffing, the token economics in detail
• Best MCP servers for coding agents