repomap

Repo map for AI coding agents. What is in this repo, in under 4000 tokens.

by Akash Priyadarshi · Patna, Bihar, India

Third of a trilogy: zcat (read a file) → rustygrep (find a needle) → repomap (orient: where am I, what is here).

Quickstart · Why · How it ranks · Flags · JSON · Architecture

---

Why

tree dumps 5000 lines and eats your context window before you read one file. An agent needs orientation first: which files matter, what they export, who imports them. repomap walks the repo, ranks files by inbound import refs, and cuts output at a token budget. You see the important files before you spend tokens reading them.

• Ranked, not listed. Files imported by others float up. Entry points sink.
• Token-capped. Default 4000 tokens. Tail truncates with a count, never silently.
• Symbols inline. Top declarations per file, first 200 lines, regex-based.
• Gitignore-aware. Respects .gitignore plus baseline ignores (VCS, caches, vendor).
• Zero dependencies. Stdlib Go only. One static binary.

Quickstart

go install github.com/AkashPriyadarshii/repomap/cmd/repomap@latest
# or build locally
go build -o repomap ./cmd/repomap

repomap                  # ranked tree, token-capped (default 4000)
repomap --budget 2000    # cap output
repomap --full           # no truncation, includes tests/vendor
repomap --json           # machine-readable
repomap --index -o index.html  # searchable HTML page, no server
repomap ./path/to/repo   # map a specific dir

Example on this repo:

$ repomap --budget 2000
└── internal/
    └── mapx/
        └── walk.go	   1 refs	2022 tokens	[supportedLang, scoreFile, clamp, firstLinesBytes, ...]

… 13 files truncated, --full to see all

1 files, 2022 tokens

How it ranks

Score per file: 0.45 × refs + 0.25 × symbols + 0.15 × size + 0.05 × symbol density. A file is important when other files import it.

• Refs: inbound import edges. Go import (...) blocks, Python import/from, JS/TS import/require, Rust use, Ruby require.
• Symbols: declaration count from the first 200 lines. Go, Python, JS/TS/JSX/TSX, Rust, Zig, Kotlin, PowerShell, Shell, Ruby, PHP.
• Budget: keeps top-N by score until the token cap, always keeps rank 1.

Token estimate is bytes/4. Close enough for a budget.

Flags

Flag	Effect
--budget N	Max output tokens (default 4000, 0 = unlimited)
--full	Show all files, skip budget truncation (includes tests, vendor, generated)
--json	Machine-readable output (same rank order)
--index	Self-contained searchable HTML page (SEO meta + client-side search)
--index-title S	Title for --index page (default "repomap")
-o FILE	Write output to file instead of stdout
--no-gitignore	Include ignored files (warning: huge)
--version	Print version

JSON mode

--json gives agents a machine map, not a human tree to re-parse:

{
  "files": [
    {"path": "internal/mapx/walk.go", "refs": 1,
     "symbols": ["Build", "parseGoImports"], "score": 0.402, "tokens": 2022}
  ],
  "total_tokens": 2022,
  "truncated": 13
}

Architecture

cmd/repomap/main.go    — flags, budget wiring, output routing
internal/mapx/
  walk.go              — walk + parallel symbol/import extraction + ref index
  symbols.go           — regex symbol patterns per language
  rank.go              — Budget() truncation (always keeps rank 1)
  render.go            — tree / JSON / HTML index renderers
  gitignore.go         — stdlib .gitignore subset (*, **, !, anchoring, dir/)

• Walk: filepath.WalkDir, skips baseline + .gitignore dirs early.
• Extract: runtime.NumCPU() workers, os.ReadFile + first-200-lines symbol scan.
• Refs: basename + dir-segment index, one count per (importer, target) edge.
• Render: ranked tree with refs/tokens/[symbols] per line, JSON, or HTML.

Non-goals

• Full gitignore parity (no nested .gitignore files yet).
• Tree-sitter parsing. Regex orients; swap only if real repos expose misses.
• Daemon mode, watch mode, incremental maps. Run it, read it, move on.

Test

go test ./...   # unit + end-to-end fixture (ranking, ignore, budget)
go vet ./...    # static check

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. See LICENSE.

---

Ecosystem & Author

Ecosystem

• design-genius
• akash-design-engineering
• tdlib-android
• kharcha

Author

• Akash Priyadarshi (Patna, Bihar, India)
• GitHub · Portfolio · LinkedIn · Resume

Social

• X / Twitter · Threads · Instagram · Reddit

---

Read with zcat. Search with rustygrep. Orient with repomap.
Keywords: repomap, repo map, code map, token budget, AI coding agents, import refs, golang cli.