renzrollon/interlock/graph

Build and query a local, deterministic codebase knowledge graph. No vector store, no external service, no network.

What gets indexed: JS/TS, Python (.py/.pyi), shell (.sh/.bash), C# (.cs, and .csproj project references), Bicep (.bicep), and curated small config JSON (package.json, tsconfig*.json — not lockfiles). Markdown stays on the bounded-retrieval path (DOCS_DIGEST.md / context / docs) plus the OpenSpec overlay — never dump every *.md into graph.json.

Languages outside that set (Go, Rust, Java, Ruby) are not structurally indexed: you still get the docs and OpenSpec overlays, but no import/symbol edges. Say so plainly rather than implying the graph is complete.

C# is inferred, not resolved. A .csproj ProjectReference is an EXTRACTED project-to-project edge. A C# type reference and a test-to-type link are INFERRED: they come from identifier matching against the namespaces a file can see, not from a compiler. Treat them as hints to verify. Four limits are known and not worked around:

• A type named only by its fully-qualified name, with no using, is not seen.
• global using applies to the file that holds it, not to its project.
• A nested type is a symbol with no record of its nesting.
• A declaration-shaped line inside a verbatim or raw string literal is a false positive.

Unreadable paths do not stop a build. A file or directory the build cannot read is skipped, and each one is named on stderr as GRAPH SKIPPED UNREADABLE: <path> (<code>). build and update still finish and exit 0; the summary line carries skipped=<n> and GRAPH_REPORT.md lists the paths under a "Not indexed" heading. Report those paths to the user rather than treating the graph as complete.

A query says when its graph is partial. query, consumers, path, explain and context print one line on stderr, GRAPH PARTIAL: <n> path(s) were unreadable when this graph was built…, whenever the graph they read was built past skipped paths. Their stdout and exit code are unchanged. When you see it, an empty or short answer is not evidence about the skipped paths: read GRAPH_REPORT.md for which they are, then Read or grep those paths directly before claiming a symbol has no other consumers.

Artifacts, all project-local under `.claude/graph/`:

Add .claude/graph/ to .gitignore — these are generated per-checkout and should never be committed.

The CLI

interlock-graph is on PATH whenever this plugin is enabled. Do not probe for it, do not build a fallback path, do not shell out to node with an absolute path.

interlock-graph --help      # full subcommand list
interlock-graph which       # print the resolved CLI path, if you need to report it

Modes

Build — when the graph is missing, or the user asks to index

interlock-graph build .

Then read .claude/graph/GRAPH_REPORT.md and summarize the top hub nodes and module boundaries. Do not rebuild on every query. If graph.json already exists, query it or update it.

Update — after merges, or when paths look stale

interlock-graph update .

No-ops when file hashes still match manifest.json.

Query — the default mode

For "where is X", "what connects to Y", "how does A reach B", "who uses Z":

1. Expand the user's wording into graph vocabulary (use labels from a prior query or from GRAPH_REPORT.md).
2. Run the matching subcommand:

interlock-graph query "<tokens>" --budget 1500
interlock-graph consumers <symbol-or-file>
interlock-graph path <A> <B>
interlock-graph explain <node>

1. Answer from the returned subgraph. Cite source_file:source_location.
2. Only then reach for Grep/Read to cover what the graph structurally cannot see: dynamic imports, string-keyed lookups, generated code, reflection.

Docs and context — bounded prose retrieval

Never read all of docs/*.md upfront.

1. Prose bootstrap — if .claude/graph/DOCS_DIGEST.md exists, read it once. Rebuild with /interlock:docs-digest when it is missing or stale.
2. Rebuild the deterministic TOC the digest is derived from:

interlock-graph docs-index . --write

1. Task-specific excerpts:

interlock-graph context "<task tokens>" --budget 2000 --changed path/a.ts,path/b.ts
interlock-graph docs "<domain terms>" --budget 800 --dirs docs,openspec/specs

context combines a structural subgraph (~45% of budget) with ranked Markdown sections (~55%). Sections cite file — heading (Lstart-Lend).

Arguments

This skill takes free text, treated as a query. Two forms are recognized ahead of that:

Note these map to CLI subcommands, not flags. There is no --rebuild or --consumers flag; interlock-graph --rebuild is an error.

When other skills call this

Follow ${CLAUDE_PLUGIN_ROOT}/shared/TOOL-ECONOMY.md and ${CLAUDE_PLUGIN_ROOT}/shared/INVARIANT-SWEEP.md.

Stance

• Graph first, files second. The graph is an index, not a substitute for reading real code when you implement or verify semantics.
• Confidence matters. Prefer EXTRACTED edges. Treat INFERRED edges (OpenSpec, memory overlays) as hints to verify, not facts.
• Never invent nodes. If the CLI reports no match, say so and fall back to grep. Do not synthesize a plausible-looking path.
• Read-only by default. build and update write only under .claude/graph/.