wiregraph / guide Install
← wiregraph

How to use it

Stand a graph up, then let Claude drive it.

Index once and wiregraph keeps itself fresh — Claude queries the graph instead of re-reading your tree. This guide walks the getting-started flow, shows how to link two separately-indexed repos so a cross-repo wire lights up, and documents every one of the 16 commands.

Getting started

Three lines to install. One to index.

Install the plugin from Claude Code, then point /wiregraph-init at a workspace. It finds every repo under the root, indexes them into one graph, and re-indexes as you edit.

1

Install the plugin

Add the marketplace, install wiregraph, reload. Public repo — native bits are prebuilt and vendored for Linux / macOS / Windows, so there's no build step.

claude-code
/plugin marketplace add kaleLetendre/wiregraph
/plugin install wiregraph@wiregraph
/reload-plugins
2

Index the workspace

Run /wiregraph-init once per workspace. It confirms scope, infers contracts for a multi-compartment root before a single build, installs the CLAUDE.md navigation directive, and turns on balanced auto-update.

claude-code
/wiregraph-init ~/log-server
3

Put Claude to work

That's it. You never call the graph tools yourself — Claude does, on every task, and the auto-update hooks keep the graph fresh as you edit. Reach for /wiregraph-status any time you want to confirm it's healthy.

⚑
Auto-update postures. off disables everything; conservative catches up at session start and nudges toward the graph; balanced (the default) also re-indexes on edit; aggressive adds optional git post-commit / post-merge hooks. A fanned-out linked peer skips only off. Change it anytime with /wiregraph-posture <level>.
off conservative balanced · default aggressive

The new capability

Join two graphs so the wire between them lights up.

Contract detection needs the two sides seen together. Repos indexed separately can't see a route they share — until you /wiregraph-link one into the other. Linking is symmetric (recorded in both graphs' configs), keeps one db per graph, and re-infers contracts over the union on every link and unlink.

edge-app GRAPH .wiregraph/graph.db · edge terminal log-server GRAPH .wiregraph/graph.db · server no code-level call ✕ contract /api/logs WIRE → postJson() producer upload handle Logs() consumer router mutual link · initiator = edge-app

Before linking, path_between returns nothing across the boundary. After /wiregraph-link, the /api/logs seam threads producer → contract → consumer — across two separate databases.

⚑
The seam fires only on a shared distinctive literal token — at least 5 characters, not a generic like /api or /health, and not a dynamically-built URL. /api/logs qualifies, and it must appear as a literal on both sides. Every link and unlink ends in a full rebuild + re-infer, never an incremental — cross-member WIRE is a full-rebuild backstop, so the two mirrored databases are eventually consistent, not lock-step.
✓ disjoint paths ✕ ancestor of self ✕ descendant of self ✕ basename collision ✕ nested in another index

Basename uniqueness is a hard requirement: compartment ids are compartment:<basename>, so two members named api would silently merge — the guard blocks it rather than warn.

Walkthrough

Two repos, no shared code — joined by a wire.

edge-app is an edge terminal that uploads logs over HTTP to /api/logs; log-server is the server that defines that route. Nothing calls across — only the wire connects them. Indexed separately, path_between returns nothing. Here's how linking joins them.

1

Index the edge repo

Stand edge-app's own graph up first. Linking never auto-initializes the near side — the directory you're standing in must already be indexed.

~/edge-app
/wiregraph-init
2

Link the server graph

From inside edge-app, link ~/log-server. The guard checks the paths, a dry-run preview states plainly that a second, unrelated repo will be written to, the peer graph is auto-created if it has no .wiregraph/, mutual link records are written to both sides, then contracts re-infer over the union and each graph full-rebuilds.

~/edge-app
/wiregraph-link ~/log-server
3

The seam traces across separate graphs

Now Claude's graph tools cross the boundary. path_between threads a chain through the contract node, and get_source on the far symbol reads straight out of the external member's real path.

MCP tools
path_between edge-app:uploadLogs log-server:handleLogsPost
get_source log-server:handleLogsPost
4

Confirm membership

/wiregraph-list gives the mutual view graph_stats can't — your own root and its compartments, then each linked root grouped beneath it, with a per-link health flag.

~/edge-app
/wiregraph-list
5

Later, sever it

/wiregraph-unlink removes the link from both graphs, prunes the member's shas on both sides, and full-rebuilds each over the reduced union so the seam disappears. Because log-server was auto-created and has no other links, it offers to remove that graph entirely.

~/edge-app
/wiregraph-unlink ~/log-server

Measured savings

See what it actually saved. Measured, not guessed.

/wiregraph-stats prints a local accounting of the tokens wiregraph kept out of your context — built entirely from what your own sessions logged, never a headline guess. It's 100% local: the log lives beside the graph and nothing is uploaded.

1

Every graph read logs what it saved

Each time Claude answers from the graph instead of opening files — get_source, trace_callers, path_between — wiregraph appends one line recording the counterfactual: the tokens it would have cost to read the files, minus the tokens the graph actually returned. That difference is the saving for that read.

2

Turns and boundaries mark the timeline

Each prompt logs a turn; each session start, /clear, and compaction logs a boundary. A boundary is where resident context resets, so this records how long a saved read stays useful. Reads are segmented per session — a boundary between two sessions stops one session's reads from ever borrowing the next session's turns.

3

The dashboard replays it into two numbers

One-time is what you'd have paid to read that code once. Recurring is that same context re-saved on every turn it stayed resident before the next boundary — because staying out of the prompt saves those tokens again each turn until context resets. The output is deterministic and relayed verbatim.

~/edge-app
/wiregraph-stats

Where the data lives — plain JSON-lines, one event per line, under the gitignored .wiregraph/ folder:

Reference

Every command. One graph.

All 16 slash commands, grouped by lifecycle. Each entry gives what it does, when to reach for it, its arguments, and a representative effect. The newer commands — the three for linking, plus review — are marked NEW.

01

Setup

Stand a graph up — from nothing to queryable.
/wiregraph-tutorial [target-dir] NEW
setup · learn

A guided walkthrough that reads your actual layout and teaches the mental model — most importantly where to init (usually the parent of your repos, so cross-repo contracts light up) and how contracts work. Explains; changes nothing until you say so.

When Before your first /wiregraph-init, or any time the compartment / contract model isn't clicking. Ends by offering to run init at the right directory for your setup.

Args optional target-dir (defaults to cwd; it inspects this and its parent to make the advice concrete)

$ /wiregraph-tutorial you're in a single repo — its siblings client/ and server/ live in ~/work → init at ~/work so the wire seam between them can be traced
/wiregraph-init [target-dir]
setup · end-to-end

Sets a project up end to end — installs deps, builds the cross-compartment call graph, installs the CLAUDE.md navigation directive, turns on balanced auto-update.

When First time you point wiregraph at a repo or workspace. Also the command Claude reroutes you to if a graph is missing. Detects an existing setup and offers Rebuild / Update / Re-initialize instead of blindly redoing it.

Args optional target-dir (defaults to $CLAUDE_PROJECT_DIR, else cwd)

$ /wiregraph-init ~/log-server scope: MULTI (3 compartments) · 1 contract inferred building… 412 files · 5 180 symbols · directive installed
02

Daily use

Keep it fresh and check on it as you work.
/wiregraph-update
daily · incremental

Incrementally re-indexes only the files changed since the last index (git diff + uncommitted edits) — not a full rebuild.

When After normal editing — the cheap, everyday refresh. Hooks do this automatically at balanced+; this is the manual trigger. Prefers the update_graph tool with no arguments.

Worktree-safe A git worktree add inside an indexed project no longer forces a full rebuild, and a rebase / amend that orphans the stored sha reconciles the affected repo by on-disk content instead of tearing the graph down. A content-hash tiebreaker confirms every mtime+size match, so a same-size edit can't slip through as unchanged.

Args none — acts on the active project

$ /wiregraph-update re-indexed 4 changed files · advanced git shas
/wiregraph-status
daily · doctor

Doctor — graph health + freshness, is the directive present, posture, whether hooks are firing, contract coverage; with a one-line fix for anything off.

When "Is my graph healthy / fresh / wired up correctly?" Triage before trusting a trace.

Args none — active project

$ /wiregraph-status graph: indexed · 412 files · 5 180 symbols freshness: STALE: 2 changed → run /wiregraph-update posture: balanced · hooks active
/wiregraph-stats [--local]
daily · savings

Prints the measured token-savings dashboard — graph-tool usage, one-time tokens saved, the measured recurring-context savings replayed from your logged sessions, and the adoption gap. Deterministic; relayed verbatim. Default is machine-wide (every graph you've init'd or linked); --local scopes it to only the current project.

When "How much is wiregraph actually saving me?" Reporting or curiosity. The numbers are local counterfactuals the script itself labels — don't reformat them. Add --local for one project's numbers on their own.

How Every graph read (get_source, trace_*) logs the tokens it saved versus opening the files; each prompt logs a turn, and each session start, /clear, or compaction logs a boundary. The dashboard replays that log — one-time is reading the code once, recurring is that same context multiplied by how many turns it stayed resident before the next boundary (staying out of the prompt re-saves it on every turn until context resets). Reads are segmented per session, so one session never borrows another's turns.

Logs Plain JSON-lines at <project>/.wiregraph/metrics.jsonl — gitignored, never leaves your machine. On update, any pre-measurement log is archived once to metrics.v1.jsonl and ignored by the dashboard, so measurement starts clean.

Args optional --local scopes to the active project (resolved from any subdirectory); no args aggregates every graph on the machine

$ /wiregraph-stats graph-tool calls: 218 · est. tokens saved: ~1.24M session context: ~1.24M once → ~5.2M recurring (measured) adoption: 82% of navigation via graph
/wiregraph-visualize [dir] [--functions|--all|--contract "<name>"]
daily · visualize

Renders the graph as a standalone offline HTML page (d3 force layout, one color cluster per repo, Contract nodes as the bridges in the middle) and opens it.

When You want to see which repos touch which contracts, or a full call graph. Everything is inlined — no network requests.

Args default (per-repo contract view), --functions, --all, --contract "<name>"

$ /wiregraph-visualize --contract "/api/logs" 42 nodes · 61 links → ~/log-server/.wiregraph/graph.html (opened)
/wiregraph-linearize <Class.method|method|ClassName> [--breadth tight|medium|full] [--depth N] [--out <path>]
daily · reading aid

Flattens a vertical call slice into one top-to-bottom pseudo-source file — follows the CALLS graph from a root symbol and inlines each reachable body once, in reading order, with a file:line banner and a back-reference on repeats.

When A flow is smeared across many files or deep call chains and you'd rather read it as a single script. It's a reading aid — the output doesn't compile. Language-agnostic and multi-compartment: it reads whatever the graph indexed, from each symbol's own compartment root.

Args root (required); --breadth tight/medium/full (how far across compartments), --depth, --file to disambiguate, --out to write a file

$ /wiregraph-linearize ProcessOrderUseCase.execute --breadth medium inlined 37 symbols · depth 9 → one top-to-bottom slice
/wiregraph-posture <off|conservative|balanced|aggressive>
daily · posture

Sets how aggressively the graph self-updates — from off (hooks no-op) through balanced (re-index on edit) to aggressive (adds git commit / merge hooks). Writes state.json; no rebuild.

When Dial a noisy repo down to conservative, or turn a hot one up to aggressive. Also how a linked peer opts out of fanned-in edits (off).

Args <posture> (required); optional target-dir, else the active project

$ /wiregraph-posture aggressive set autoUpdate posture to "aggressive"
03

Graph & contract ops

Rebuilds, seams, and the AsyncAPI draft.
/wiregraph-rebuild [target-dir]
ops · full rebuild

Full from-scratch rebuild — the correctness backstop. Routes through the union-aware full build, so it preserves linked members.

When After big refactors or renames (incremental is approximate for incoming edges to renamed / removed symbols), or whenever a trace looks wrong. Prefers update_graph { full: true }.

Args optional target-dir (defaults to active project)

$ /wiregraph-rebuild full reset over 2 members (log-server + linked edge-app) 5 180 symbols · 1 contract · 2 WIRE (members preserved)
/wiregraph-contracts [target-dir]
ops · infer seams

Infers cross-compartment wire seams (an endpoint one compartment defines and another calls) and proposes an AsyncAPI contract linking producer → consumer.

When A multi-compartment workspace where you want trace_contract / path_between to follow the wire. Attribution needs the compartments indexed together — repos indexed separately need /wiregraph-link.

Args optional target-dir; scan → confirm → apply

$ /wiregraph-contracts scan: 1 wire seam · HTTP /api/logs wrote contracts/wiregraph-inferred.asyncapi.yaml
/wiregraph-review [target-dir]NEW
ops · doc-vs-reality drift

Reviews a compartments-and-contracts project for drift between its documentation and its reality — the directory tree, the per-compartment whoami.md files, the contract index, and the structure document — and fixes what the spec already settles.

When The architecture is cheap to design but comes apart quietly — a compartment gets added and never reaches the index, a contract is written and never listed. A script finds every finding as a set difference or stat; Claude never re-derives drift, only relays the findings and edits the files the script names.

Args optional target-dir (defaults to the active project); --structure <path> if the structure doc isn't project-structure.md

$ /wiregraph-review parsed 14 index rows · 3 findings: 1 compartment unlisted, 2 contract paths off
⚑
CALLS edges are within-compartment by design. Cross-compartment links flow only through Contract nodes — so a rename on one side of a seam shows up as the contract's two edges no longer agreeing, which a plain call graph never records.
04

Linking separate graphs

Mutual, one-db-per-graph, always full-rebuild + re-infer.
/wiregraph-link <dir>NEW
link · include a member

Includes an external, code-disconnected directory as a member of this graph, so cross-repo wire / contract seams light up across two separately-indexed graphs.

When Two repos are joined only by a wire — an HTTP call, a topic, a shared-state key — with no direct code calls. Auto-inits the peer graph if it has none, writes symmetric link records to both sides, then re-infers contracts over the union and full-rebuilds each graph.

Args <dir> — the external directory to link (required)

$ /wiregraph-link ~/log-server guard ✓ → preview → auto-init peer → mutual write re-infer → rebuild both · trace_contract "/api/logs"
/wiregraph-unlink <dir>NEW
link · remove a member

Removes a linked member; both graphs full-rebuild over the reduced union and the seam between them goes away.

When You linked the wrong thing, or the relationship no longer holds. Removes the entry from both graphs and prunes shas on both sides. If the peer was autoCreated and now has no other links, it offers to remove that graph entirely; a pre-existing peer is only unlinked, never deleted.

Args <dir> — a currently-linked member

$ /wiregraph-unlink ~/log-server removed link on both sides · both rebuild · 0 WIRE offers to remove the auto-created log-server graph
/wiregraph-listNEW
link · membership

Shows this graph's membership — the mutual view graph_stats can't give.

When Audit what's linked, confirm a link is mutual (not half-written), or spot a member whose directory vanished. Flags each link mutual or one-sided (repair by re-running /wiregraph-link).

Args none

$ /wiregraph-list Own root: /home/dev/edge-app → edge-app Linked: /home/dev/log-server [mutual] → api, worker, shared
how linking behaves

Linking is symmetric — recorded identically in both graphs' configs. Each graph keeps one db and stores the union under its own project tag (node ids are project-free). Every link / unlink ends in a full rebuild + re-infer, never an incremental — so the two mirror dbs are eventually consistent, not lock-step.

05

Teardown

Back out cleanly — pause, or fully uninstall.
/wiregraph-teardown [target-dir]
teardown · soft

Soft-remove — strips the managed CLAUDE.md block and sets posture off so hooks no-op; leaves graph.db + state.json for instant re-init.

When Pausing wiregraph on a project but you'll likely come back — no need to rebuild later.

Args optional target-dir

$ /wiregraph-teardown removed managed CLAUDE.md block · posture → off left intact: .wiregraph/ — re-init is instant
/wiregraph-remove [target-dir]
teardown · hard

Hard-uninstall — deletes the .wiregraph/ folder, the managed directive block, the .gitignore entry, and a dangling ~/.wiregraph symlink. Nothing else touched.

When Done with wiregraph on this project entirely. Destructive — previews with --dry-run and requires explicit confirmation.

Args optional target-dir

$ /wiregraph-remove --dry-run would remove: .wiregraph/ · directive · .gitignore line proceed? › yes · source untouched

teardown

pause — you'll come back
  • ✓ keeps graph.db + state.json
  • ✓ re-init is instant
  • ✓ posture set to off (hooks no-op)
  • ✓ managed CLAUDE.md block removed

remove

done — uninstall entirely
  • ✕ deletes the whole .wiregraph/ folder
  • ✕ deletes graph.db, state.json, refresh.log
  • ✕ removes the .gitignore entry
  • ✕ removes the directive block + symlink

Ready

Index once. Then link the seams.

Stand a graph up with /wiregraph-init, join separately-indexed repos with /wiregraph-link, and Claude traces producer → contract → consumer across every boundary — at about half the tokens.

Install wiregraph  →