An agent that explains a codebase by reading it, not its README

Ask a model about a well-known repository and you will get a fluent answer assembled from its README, its docs site, and whatever was said about it on the internet before the training cutoff. It will be confident, mostly right, and describe the project as it was two years ago. Repo Explainer clones the thing and reads it.

Many files, one note, and a path behind every claim. The lines converge rather than branch — a repository diagram usually fans outward, which is exactly the shape this agent refuses to produce.

Two rules, and everything else follows from them

Rule one: start where execution starts. Not at the alphabetical top of the file tree, not at the largest file, and not at the README. Find the entry point — the binary, the server bootstrap, the exported module — and read outward through what it actually reaches.

This is the difference between an architecture note and a directory listing with adjectives. A tour that starts at src/ and works down tells you what exists. A tour that starts at index.ts and follows the calls tells you what runs, and in what order, and what is dead.

The reading order. The ringed node is where execution starts; the traced path is what that file actually reaches. The faded boxes are the rest of the repository — present, and deliberately not read.

Rule two: every claim carries its path. Not a footnote, not a bibliography at the end — the file and, where it matters, the line, inline with the sentence that depends on it.

Requests are retried with exponential backoff and full jitter (source/core/Request.ts:214), but only for idempotent methods — a POST that times out is surfaced rather than repeated (source/core/options.ts:88).

That sentence is checkable in ten seconds. The same sentence without the paths is something you have to take on trust from a system that has no particular reason to deserve it, and the difference is the entire value of the output.

It clones the repository, so the answer is about this version

The agent has a Linux sandbox and it uses it the way you would:

Bash

git clone --depth 1 https://github.com/sindresorhus/got
cd got && git log -1 --format=%H
# 4f2b3a9... the commit the note is about

A shallow clone, because history is not the question. What matters is that the note describes the code that exists today rather than the code that existed when a model was trained — and that if you re-run it in six months, the answer changes, because the repository did.

It can also ask DeepWiki, and it knows which one to trust

The agent has an optional MCP connection to DeepWiki, which holds pre-built indexes of a great many public repositories. That is genuinely useful for orientation: it answers “what is this project for” in one call instead of thirty.

The prompt is explicit that the two sources are not interchangeable. DeepWiki is for orientation and for questions about a repository too large to read in a run. The clone is the authority. Where they disagree, the working tree wins and the disagreement is worth mentioning, because an index that is a release behind is exactly how a confident wrong answer gets made.

The section people test it on

Every note ends with what the agent did not read. Not a disclaimer — an actual list: the directories it skipped, the generated code it ignored, the test suite it only sampled, the parts it ran out of run budget for.

This is the section reviewers check first, and it is the one that makes the rest usable. An architecture note that implies complete coverage is a note you cannot safely act on, because you do not know where its blind spots are. One that names them lets you decide whether the gap matters for what you are about to change.

What it found in us

Building this agent broke our own API. Reading a repository properly is a great many small calls — list, open, search, open again — and one worst-case turn of this agent makes about 75 requests. Our rate limit was 60 a minute.

We had picked that number for someone abusing the platform. The first client ever to hit it was the product doing exactly what it is for, which is a useful thing to learn from a tool rather than from a customer. The whole run of that story is in the series post.

Good first questions

“Write me an ARCHITECTURE.md for sindresorhus/got.”
“Where does this project handle authentication, and what happens when a token expires?”
“I need to add a new storage backend. Which files would I be touching, and what contract do they implement?”

The last one is the one it is genuinely good at, and the reason to reach for it: not summarising a codebase, but answering a question you would otherwise spend an afternoon reading to answer yourself.

Open Repo Explainer.