repo-map

# repo-map Produces a **ranked list of the structurally-important symbol definitions** in a codebase, capped to a token budget. The point: instead of dumping whole files (wasteful, blows the context window), get a cheap "skeleton" of the repo — the functions/classes everything else depends on — and read full files only where it matters. This is our zero-dependency port of [Aider's repo-map](https://aider.chat/docs/repomap.html). ## When to use - **Onboarding** to an unfamiliar or large codebase — get the lay of the land first. - **Before a refactor / `deep-review` / `workflow-orchestration` fan-out** — feed each subagent the map so it knows the important entry points without re-scanning. - **JIT context** (principle 07 / `practice_context_engineering`) — load the map, not the files. - Anytime the instinct is "let me read 20 files to understand this" → run this first. ## Usage ```bash python scripts/repo_map.py [ROOT] [--budget-tokens N] [--top N] [--json] [--no-signature] [--max-files N] ``` - `ROOT` — repo root (default: cwd). If it's a git repo, only **tracked files** are scanned (honors `.gitignore`); otherwise a filtered directory walk is used. - `--budget-tokens` (default 1024) — stop emitting once ~this many tokens are used (≈4 chars/token heuristic). Use 256–512 for a quick orientation, 2048+ for depth. - `--top N` — hard cap on symbols before the budget applies. - `--json` — machine-readable output (for piping into a workflow / another agent). - `--no-sig...