Building repomap - Answering "What's In This Repo" in Budget Tokens

Every AI agent session starts with the same question: what's in this repo? The answers today are either a directory listing (no signal) or dumping whole files into context (bankrupt).

repomap is the third piece of the read→search→orient pipeline I've been building — after zcat and rustygrep. It answers "what's here" in a bounded token budget.

What it does

repomap walks a repo and produces a ranked map: which files matter, what symbols they define, where the import references point. Sorted by importance, so the first lines are the ones an agent actually needs to read.

The budget is the whole point. --budget N hard-caps the output to N tokens. The map fits in the context window or it doesn't ship. Same instinct as rustygrep's --llm-budget — respect the window.

How it ranks

Files are scored by fan-in — how many other files reference them. A type that twenty files import outranks a utility only one file uses. Symbols inside a file get the same treatment. It's not magic, it's the same signal a senior dev uses to answer "where do I start."

The trilogy

zcat reads a file, cheap. rustygrep finds the line, cheap. repomap tells you which file to look in at all, cheap. On their own each is a small tool. Together they're the orient loop an agent runs a hundred times a session.

What's next

Gitignore and build-system awareness so generated files don't pollute the map. Language coverage beyond the core set — the ranking needs a proper parser per language, and that's the long tail.

---

Built on tree-sitter. Written in Go, single binary. The budget flag is the API — everything else is default.