I built a tool that gives AI coding agents a map

What happened when I asked "why does my AI assistant start every session lost?"

Every time you open an AI coding assistant in a real codebase, the same thing happens. It greps around. It opens a few files. It reads your README, maybe a config. Then it starts answering from a keyhole view of a codebase that might be hundreds of thousands of lines, years of decisions, and dozens of half-finished branches.

The assistant isn’t dumb. It’s blind. Nobody gave it a map.

The day I made the map by hand

I work on a Go monorepo that runs a trading protocol’s backend, two services, about 150,000 lines, 400+ pull requests, 126 branches. One day I wanted the whole picture: every branch, every PR ever opened, how the modules depend on each other, how the system actually flows end to end.

Building it took a full day of what I can only call archaeology. Cross-referencing every branch against every PR to figure out which were truly merged, which were squash-merged (git can’t tell you this ancestry is silent about squashes), which were abandoned. Tracing import graphs. Reconstructing the project’s history into eras. The result was a 650-line document that made the whole codebase legible to me, and to any AI agent I pointed at it.

It was the most useful document in the repo. And it was rotting from the moment I wrote it. Two days later the branch counts were already wrong.

The insight: the map has two layers

Here’s what building it by hand taught me. A codebase knowledge graph is really two different things glued together:

1. A deterministic layer - facts a machine can extract with certainty. Which modules exist and how big they are. Which module imports which. Which branches merged, which PRs died. What the CI does. None of this needs an AI, and none of it should be written by one, because machines don’t misremember.

2. A narrative layer - the why. What each module is for. How a request actually flows through the system. The gotchas that will bite you. This layer genuinely needs intelligence but here’s the trick: it changes slowly. Your architecture’s purpose is stable even while its line counts churn daily.

Most tools in this space pick one layer and fake the other. Static tools generate structure and pretend it’s understanding. LLM tools generate understanding and quietly hallucinate structure.

So I built repokg

One command:

uvx repokg .

A few seconds later you have KNOWLEDGE_GRAPH.md module inventory, import graph with a diagram, every branch classified against every PR, contributor history, a timeline of the repo’s evolution, the full ops surface, plus kg.json, the same graph machine-readable.

That’s the deterministic layer, extracted fresh every run. The branch-vs-PR forensics alone justify the tool for me: it distinguishes merged from squash-merged from abandoned from stale by cross-referencing git ancestry with the PR record and the analysis that took me hours by hand.

For the narrative layer, repokg does something I haven’t seen elsewhere: it refuses to guess, and delegates honestly. It emits a rigorous prompt that your coding agent, Claude Code, Cursor, whichever executes: read the code, verify every claim, write your findings into one schema-validated JSON file. Render again, and the narratives merge into the document. Regenerate next week and the structure refreshes while the narratives persist. The map stops rotting.

Honesty as a feature

Some things a scanner concludes are heuristics, and pretending otherwise is how tools lose trust. So every inference in repokg carries a confidence label and its evidence, and repokg audit shows you exactly what was measured versus guessed:

[git]
  trunk = master          high    detected via origin/HEAD symref
  integration = staging   medium  matched a well-known branch name
[modules]
  4 flagged generated     low     path-name heuristic; verify first

The same philosophy runs through everything: repokg inject adds one clearly-marked block to your CLAUDE.md or AGENTS.md and never touches anything else; repokg clean provably reverses everything the tool ever wrote; repokg check fails your CI when the graph goes stale instead of letting it lie.

And the whole thing is zero-dependency Python pure standard library.
pip install repokg brings nothing else with it.

What surprised me

The hand-built document I spent a day on? The tool now regenerates a larger, fresher version of it in about four seconds — and the narrative layer, written once by an agent following the enrichment prompt, survives every regeneration.

The map problem was never really about my one repo. Every AI-assisted team is quietly re-deriving their codebase’s shape, one blind grep session at a time.

It’s open source

MIT, on GitHub, pip install repokg. The roadmap is public and deliberately contributor-shaped, every issue ships with a stacked-PR plan so you can land something real in an afternoon: Java and Kotlin import graphs, a GitHub Action, MCP server mode so agents can query the graph instead of reading it.

Give your agent a map. It stops guessing.