What an Agent Needs Before It Can See Your Repo

The repository sits on a disk somewhere, and to the agent it is a dark room. Before any of the interesting work (reading the code, tracing a bug, proposing a fix) can begin, someone has to switch on the lights. That switching-on is the whole subject. An agent that can query a repo is not the same as an agent that can see it, and the gap between those two conditions is where most of the real engineering lives.

Picture the most common failure. A developer wires an LLM to a shell and lets it run commands. The agent types ls, gets a wall of filenames, types cat on one of them, gets four thousand lines of minified JavaScript, and promptly loses the thread. It has access. It does not have vision. The distinction matters because access is cheap and vision is expensive, and pretending otherwise is how teams end up with a demo that impresses for ninety seconds and a product nobody trusts.

What follows is a list of the things an agent actually needs before it can see a repo. Not the marketing list. The working list, the one that comes from watching agents flail on real codebases.

A map, and a sense of its scale

The first thing an agent needs is a structural view of the repository: the directory tree, the languages present, the rough line counts per module, the build files, the package manifests. This sounds trivial. It is not, because the useful version of a map is scaled to the repo.

A small library with forty files can be presented almost whole. A monorepo with four hundred thousand files cannot be, and any attempt to shove it into context produces the agent equivalent of a person trying to read a city by staring at a satellite photo. The agent needs to know which of those two situations it is in before it decides how to look.

Concretely, that means the agent should receive a summary that includes total file count, a breakdown by extension, the top-level directory sizes, and a flag for generated or vendored code. Generated code is the trap. An agent that does not know node_modules or a dist folder exists will happily read ten thousand lines of bundled output and conclude the codebase is a mess of anonymous functions. Mark those directories as dark zones and the agent's first hour gets dramatically more useful.

A way to find the one file that matters

Repos are mostly irrelevant to any given task. A bug report about a login timeout touches maybe six files out of six thousand. The agent needs a retrieval mechanism that can zero in on those six, and it needs the mechanism to be cheap enough to run dozens of times per conversation.

Plain grep is underrated here. So is a symbol index. The best setups combine three moves: full-text search for strings, a symbol search for function and class names, and a semantic search over file summaries. Each catches a different kind of question. If the agent knows the exact error message, grep wins instantly. If it knows a function name, symbol search wins. If it only has a vague description of behavior, semantic search is the last resort, and it should be treated as a last resort because it is the least reliable of the three.

An agent that only has semantic search will wander. An agent with all three will, in my experience watching these systems, find the relevant file in a handful of calls. That difference compounds across an entire session.

The ability to read a file without drowning in it

Reading a file is not the same as loading it. A two-thousand-line file that gets dumped into context whole will push out everything else the agent was holding. The agent needs the ability to open a file at a specific range, to search within a file, and to get a summary of a file's exports and imports without reading the body.

This is where a lot of naive tooling falls down. The interface offers "read file" and nothing else. The agent, trying to be careful, reads the whole thing, and now half its context window is gone on a file it needed three lines from.

A good file-reading interface looks more like an editor than a cat command. It lets the agent jump to a line number, read a window around a match, and pull just the function signature. These are small affordances. They add up to the difference between an agent that can explore and one that gets one look and then has to stop.

History, because the present is half a story

Code carries its reasons in its commit log. The agent that can see git history can answer questions the current files cannot. Why is this function wrapped in a try/catch that swallows the error? A blame lookup points to a commit from two years ago whose message says the third-party API throws on empty responses. That is a fact the code itself has erased.

An agent needs at minimum the ability to see recent commits, to blame a line, and to read the diff of a specific commit. Without this, it will confidently propose removing code that exists for a reason, and the reason will be invisible to it.

There is a subtler benefit. History tells the agent what kind of codebase it is in. A repo with disciplined conventional commits and small diffs is one where the agent can propose a change and expect review. A repo with thousand-line commits and messages like "fix stuff" is one where the agent should tread more carefully and surface more uncertainty. The commit log is a personality test for the project.

Tests, as an oracle the agent can actually run

The single most useful thing an agent can do with a repo is run the tests after making a change. This requires that the agent knows how to run them, which is not always obvious. Some repos use make, some use a package script, some use a bespoke shell file that nobody has touched in three years.

Before the agent can see the repo, then, it needs a test command it can execute and a way to read the results. That means a sandbox where running tests is safe, a timeout so a hung test does not stall the whole session, and a parser that turns test output into a short list of pass and fail rather than a thousand lines of log.

When no tests exist, the agent should know that too. A repo without tests is a repo where the agent's confidence should drop a notch, and where its proposals should be framed as suggestions rather than fixes.

The conventions nobody wrote down

Every codebase has house rules. Error handling lives in one module and not another. Tests go in a folder named with a specific suffix. New dependencies require an entry in two files. None of this is in the README.

An agent that cannot see these conventions will produce code that works and gets rejected in review. This is one of the quieter failure modes and one of the most frustrating for the humans involved, because the agent's output is technically correct and socially wrong.

The fix is to give the agent examples. When it proposes a change, it should be able to retrieve three or four existing files that look like the one it is editing and use them as style references. A pattern library of the repo's own code, sampled live, does more for output quality than any amount of instruction in a system prompt.

A boundary between reading and writing

Seeing a repo and touching a repo are different permissions, and the agent should experience them as different. A read-only phase where the agent explores, greps, reads, and plans is where most of the value gets created. The write phase, where files are actually modified, should be a distinct step with its own confirmation.

Collapsing the two into one capability is a common mistake. It feels efficient. In practice it produces agents that edit before they understand, and humans who stop trusting the tool after the second surprise diff. The separation is not bureaucracy. It is the thing that makes the agent's edits reviewable.

A budget, stated plainly

Every exploration costs tokens and time, and the agent should know its budget up front. An agent that thinks it has unlimited room to explore will do exactly that, spiraling through directories until context runs out mid-thought. An agent told it has, say, twenty tool calls to find the bug will prioritize.

The budget should also include a wall-clock limit and a token ceiling, and the agent should be instructed to report what it did not get to when it hits either one. An honest "I found the likely cause but did not verify the fix because I ran out of room" is worth more than a confident guess, and the agent will only produce that report if the budget is visible to it.

What the repo looks like when all of this is in place

With a map, three kinds of search, ranged file reads, history access, a runnable test command, live style examples, a read/write split, and a stated budget, the agent's behavior changes in a way that is easy to spot. It asks fewer redundant questions. It opens the right file on the second try instead of the eighth. Its proposed diffs match the surrounding code. When it is unsure, it says so specifically: "the config loader is in one of two files and I could not tell which without running the tests."

That last behavior is the real signal. An agent that can see the repo knows what it cannot see. The dark corners become explicit rather than silently mistaken for empty space. A team can read that honesty and act on it. A team staring at an agent that guesses confidently has nothing to work with at all.

The work of giving an agent sight, then, is mostly the work of building a good pair of glasses: shaped to the repo, honest about the blind spots, and cheap enough to keep on. The models will keep improving. The glasses are the part that has to be made by hand.