repomap
Repo map for AI coding agents. Answers “what’s in this repo” in the fewest tokens — orient before you read or search.
Third of a trilogy: zcat (read a file) → rustygrep (find a needle) → repomap (orient: where am I, what’s here).
Why
tree drowns an LLM context window before the agent reads one file — and a
5000-line listing is useless. repomap walks the repo, ranks files by
importance for an agent, and emits a token-budgeted map.
Install
go install github.com/AkashPriyadarshii/repomap/cmd/repomap@latest
# or build locally
go build -o repomap ./cmd/repomap
Usage
repomap # ranked tree, token-capped (default 4000)
repomap --budget 2000 # cap output
repomap --full # no truncation
repomap --json # machine-readable
repomap --no-gitignore # include ignored files (warning: huge)
repomap ./path/to/repo # map a specific dir
Example
$ repomap
├── cmd/server/main.go 59 refs 12 symbols [main, setupRouter, serveHTTP]
├── internal/auth/
│ ├── jwt.go 41 refs 8 symbols [Issue, Verify, ParseToken]
│ └── middleware.go 22 refs 4 symbols [RequireAuth, OptionalAuth]
│
… 412 files truncated, 3,214 symbols hidden (--full to see all)
JSON
repomap --json — same pattern as zcat/rustygrep. Agent gets a machine
map, not a human tree to re-parse:
{
"files": [
{"path": "cmd/main.go", "refs": 12, "symbols": ["main", "setup"], "score": 0.9, "tokens": 180}
],
"total_tokens": 3900,
"truncated": 412
}
Docs
- docs/PRD.md — product, goals, interface
- docs/design.md — architecture, ranking, budget
- docs/impl.md — implementation plan
- docs/CLAUDE.md — project conventions
License
MIT