ripwire-repo-map

# ripwire — deterministic repo map before reading code `ripwire` (v0.4.x at authoring time; the release binary must be on PATH) is a zero-dependency C++23 CLI that builds a ranked, deterministic call graph of any repo in ~1s (parses once, then auto-caches warm). It answers "what to touch, what it breaks, which tests to run" for a fraction of the tokens of grep + whole-file reads. No API key, no daemon, no index server, offline. Invoke it via the terminal tool. ## When to reach for it (instead of blind grep / whole-file reads) - Landing cold in a repo or subsystem — "what's here, how is it organized, what matters" - "Where is the code for X" — a task, feature, or concept in your own words - A change is proposed — what breaks, who calls it, which tests must run - Resuming work after compaction / a new session on in-flight work - Reviewing code you did not write (fresh eyes), or pre-commit change vetting Do NOT use for trivial single-file lookups (plain `rg`/search_files wins) or broad common-word questions — ripwire shines on specific technical asks. ## Core verbs (all take a repo dir; `--help` is authoritative) ```bash ripwire <dir> --report # architecture summary: modules, god-files, cycles, top symbols ripwire <dir> --for="<task in your own words>" # ranked task lens: what to touch first, with 1-hop edges ripwire <dir> --callers=someFunc --legend=compact # who calls it (blast radius) ripwire <dir> --test-gate --legend=compact # which tests must run before committing ripwire <dir> --tree --legend=compact # file-by-file: top symbols per file ripwire <dir> --hotspots --legend=compact # files ranked by churn × complexity ripwire <dir> --communities --legend=compact # cohesive modules (Louvain) + bridges — where a new feature belongs ripwire <dir> --situ # what the working tree already changed + its blast radius (resuming work) ripwire <dir> --notes --legend=compact # pinned gotchas from past sessions (field notes) ripwire <git-url> # orient in a remote repo (shallow-clones into a cached temp dir; --refetch refreshes) ``` Read the map, then open only the files it surfaces (god-files and hotspots first). For a body of one ranked symbol: `ripwire <dir> --for="..." --expand=path:name` (paste `p=`/`n=` off the row). ## Honesty signals — read them before trusting a result - The `--for` lens reports `confidence=`/`margin_pct=` on its result root and the output carries `est_tokens=` — `confidence="low"` or a flat ranking means treat the set as a starting point, not an answer. - `--for` bundles: `bodies="0"` = no full bodies shipped (`reason="compact-route"`; `--auto-bodies` restores them. A `reason="budget"` means the caller's token budget cut them — raise the budget instead). - `--skipped` lists files the index dropped (oversize, or `.gitignore`d — default ignored; `--no-ignore` restores the full walk). A "not found" is only trustworthy after checking this. - `amb="K"` on a symbol means K of its outbound calls matched several possible definitions — the resolver split the weight instead of choosing one. Read the source if the target matters. (`lpin=` is a separate, disclosed guess the resolver made; same remedy.) ## Pitfalls 1. **First call on a tree parses** (~1s at 1,500+ files; measured ≈1.2s wall for a 2,355-file / 77k-edge checkout on Apple M2). Later calls are warm and near-instant — chain verbs freely. 2. `--top-k` is NOT read by `--for`'s own bundle (it shapes the default map and `--query`; it still applies to `--format=candidates` with `--for`). 3. Markdown/docs-only or shell-only repos yield few call-graph edges — `--report` is still useful, edges are not. 4. The tool indexes signatures, not necessarily full bodies, by default on conceptual queries — `--expand` or `--auto-bodies` when you need the body. 5. Cache/notes live in the repo tree (`.ripwire_notes` for `--note-add`); the notes file is meant to be committed. 6. ripwire output can be large on big repos — budget with `--max-tokens=8000` / `--top-k=50` where supported. ## Reference links - Upstream: https://github.com/redhat-et/ripwire (Apache-2.0; releases ship prebuilt macOS/Linux binaries + SHA-256) - The project ships 18 agent skills (Claude Code/Codex format) under `skills/` in its repo — this Hermes skill is the distilled Hermes-format counterpart to that family (`ripwire-orient` is the closest base); read those upstream for deeper flows.