By name: repomap description: "MUST invoke this skill for ANY task that touches code — before reading, editing, searching, debugging, refactoring, navigating, understanding, deleting, renaming, or moving code. Before every grep, every find, every file read, every edit, every symbol lookup, every impact check, every dependency question. After every edit for verification. Also invoke for: investigating bugs, planning features, reviewing PRs, assessing dead code, mapping API routes, tracing call chains, checking diagnostics, auditing state machines. The only exceptions: single-character typo fixes, pure prose/doc edits with zero code impact, and purely non-coding conversations. When in doubt whether to invoke, invoke it."
repomap
repomap is a CLI tool that builds a codebase graph (tree-sitter AST → symbols → dependencies → PageRank) and answers structural questions faster than grep + raw reads.
Usage
repomap <command> [--project <path>] [options]
--project is optional. If not specified, repomap auto-detects the git root directory.
Core Rules
- Repomap first, grep later. Use repomap commands instead of grep/find for code understanding.
- TIMEOUT: 120 seconds minimum. Every bash command invoking repomap MUST use timeout ≥120s.
- LSP is automatic.
query --symbol,call-chain,query --file,verify, andcheckuse LSP when available. verifyafter edits. Run after every non-trivial code change.impactbefore edits. Run before non-trivial edits to assess blast radius.
Commands
| Situation | Command | Notes |
|---|---|---|
| Project overview | overview |
Modules, entrypoints, reading order, hotspots |
| Find symbol | query --symbol <name> |
LSP precision, state map for enums |
| Call flow | call-chain --symbol <name> |
Callers, callees, references |
| Topic search | query --query <keyword> |
Synonym expansion, relevance ranking; returns empty with message when no matches |
| BM25 search | query --search <text> |
BM25 symbol ranking |
| Read a file | query --file <path> |
Symbols, signatures, callers, LSP tree |
| Impact analysis | impact --files <f...> --with-symbols |
Blast radius, suggested tests; --compact for concise output; --top-n <N> to limit files |
| Discover affected tests | affected --files <f...> |
Reverse dependency tracing from changed files; --stdin for pipe mode, --filter for custom pattern |
| Post-edit verify | verify |
Git changes, risk, diagnostics, orphan symbols, graph diff, cascade callers, secrets scan; --risk-threshold HIGH|MED|LOW; --no-cascade; --no-secrets |
| Quick check | verify --quick |
Git changes + risk only |
| Lint diagnostics | check |
Compiler/lint errors |
| Auto-fix | fix |
Multi-language formatters (ruff, biome, prettier, eslint, gofmt, cargo fmt) with config-gated nearest-wins detection |
| Pre-commit | ready |
verify + check + format |
| API routes | routes |
HTTP route inventory |
| Prepare for changes | cache save |
Baseline snapshot for verify diff comparison; auto-prunes session caches older than 7 days |
| LSP status / setup | lsp doctor / lsp setup |
Detects and installs language servers |
| Health check | doctor |
Runtime + LSP server availability |
Value-Added Features (Auto-Enabled)
- verify — high-confidence orphan symbols (≥70), call-graph consistency check (broken call/import edges), graph diff (when baseline exists), cascade caller analysis (≤2 hop, top-10), and secrets scanning (gitleaks → detect-secrets → builtin)
- query --symbol — state map for enum/const symbols and references
- call-chain — all references
- overview — hotspot files
- doctor — LSP server status
Workflows
New repo
overview→ grasp structuredoctor→ check runtime + LSP availability
Edit file
query --file <f>→ understand before touchingimpact --files <f> --with-symbols→ assess blast radius- Edit
verify→ evidence gate (includes graph diff)
Change symbol behavior
query --symbol <name>→ find definition + state mapcall-chain --symbol <name>→ understand call flow + references- Edit
verify
Delete code
verify→ check orphan symbols (≥70 confidence)- Check for dynamic references (string dispatch, reflection, macros)
- Delete
API change
routes→ route inventoryimpact --files <route-file> --with-symbols→ blast radius- Edit
verify
Call Budget
| Project Scale | File Count | Max query Calls |
Max call-chain Calls |
Recommended Strategy |
|---|---|---|---|---|
| Small | <500 | 3 | 2 | Query directly |
| Medium | <5000 | 5 | 3 | Start with overview to narrow scope |
| Large | ≥5000 | 4 | 2 | Must start with overview + impact |
Budgets are based on repomap real-time scan latency, not persisted graph queries.
Diagnostic Decision
| After editing… | Use | Time | What it checks |
|---|---|---|---|
| Just saved a file | verify --quick |
~2s | Git changes + risk level only |
| Ready to commit | verify |
10–30s | Full evidence: changes, risk, orphan symbols, LSP diagnostics, graph diff |
| Need compiler/lint errors | check |
varies | Standalone diagnostics (eslint, tsc, ruff, go vet) — no git dependency |
| CI pipeline | check + verify |
varies | Diagnostics first, then full evidence gate |
Rule: verify --quick after each edit. verify before commit. check when you need diagnostics independent of git state.
Critical Rules
checkreportsunknown→ no diagnostic tool ran; investigatecheckreportsparse_error(truncated=True) → diagnostic tool ran but output could not be parsed; investigate project config or tool versionverifysaysSKIPPED→ state limitation; state it explicitlyverifysaysNO_CHANGES→ no git changes detected, cannot assess risk; distinct fromSKIPPEDverifyreports contract risks → address each before claiming completion
Session Flags
cache save— Run BEFORE a refactoring session. Saves a graph baseline soverifycan show a before/after graph diff. Automatically prunes stale session caches (TTL 7 days). Skip for isolated single-file edits.cache prune— Manually remove stale session caches older than--ttl-days(default 7).--with-co-change— Enable for HIGH-RISK edits (changing exported symbols, core modules). Uses git history to find files that are often modified together. Adds 30–60s. Skip for routine edits.--no-incremental— Force a full rescan, ignoring cached data. Use when cache may be stale (switched branches, pulled new commits, getting unexpected results).
Capabilities
| Feature | Coverage |
|---|---|
| Call graph | Python, TypeScript/TSX, Go, Rust, Java, C#, C++ (tree-sitter, 7 languages) |
| Type inference | Python, TS/TSX, Go, Rust, Java, Kotlin, Swift, C#, C++, PHP (11 languages) |
| Parsing | Python, JS/TS/TSX, Go, Rust, Java, Kotlin, Swift, C/C++, C#, PHP, Ruby, Lua, HTML, CSS, JSON, YAML, Bash (17 languages) |
| Git backend | pygit2 (libgit2) when available; subprocess fallback |
| Search | BM25 ranking with keyword fallback |
| LSP | Default-on when available, local-only |
Boundaries
- Prefer repomap over grep/reads when repository intelligence reduces uncertainty.
- Quote only real CLI output; do not guess.
verifyrequires a Git repository.- Path-taking commands normalize
./...and absolute paths.