graph-indexer 2.1.1 → 3.0.1

package/SECURITY.md

@@ -10,7 +10,7 @@ Please include:
 
 - A description of the vulnerability and its impact.
 - Steps to reproduce (a minimal proof of concept if possible).
-- The affected version (`graph-indexer --version` or the `version` field in `package.json`).
+- The affected version (`graph-indexer status` prints it, or see the `version` field in `package.json`).
 
 You can expect an initial acknowledgement within **5 business days**. Coordinated
 disclosure is appreciated — we will work with you on a fix and credit before any
@@ -18,68 +18,63 @@ public discussion.
 
 ## Supported versions
 
-Security fixes are applied to the latest published `2.x` release. Older versions
+Security fixes are applied to the latest published `3.x` release. Older versions
 are not maintained; please upgrade to the latest version.
 
 ## Security posture
 
-graph-indexer is designed to run locally as a developer tool. Its threat model is
-shaped by a few deliberate choices:
+graph-indexer is a local developer tool. Its threat model follows from a few deliberate choices:
 
-- **Air-gapped by default.** In normal operation the only outbound network call is to
-  a *local* Ollama endpoint (`OLLAMA_HOST`, default `http://localhost:11434`) for
-  embeddings. With `INDEXER_EMBEDDINGS=off`, even that call is skipped and the tool is
-  fully offline. There are no analytics, telemetry, crash reporters, or third-party API
-  calls. **One exception:** the optional in-process embedding provider
-  (`embedProvider: "local"`, or `"auto"` when no Ollama is found) downloads its model
-  weights from the Hugging Face CDN **once** on first index, then runs fully offline
-  from the local cache. Your source code is never sent anywhere — only model weights
-  are fetched. For strictly air-gapped installs, set `embedProvider` to `"ollama"` or
-  `"off"`, or pre-populate the model cache on a connected machine.
-- **Sealed mode (opt-in, fail-closed enforcement).** For regulated or strictly
-  air-gapped installs, `--sealed strict` (`INDEXER_SEALED`) enforces **zero** network
-  egress (lexical-only), and `--sealed local` permits **loopback only** (a local
-  Ollama/MLX on this box is allowed, nothing leaves it). It is *fail-closed*: the build
-  refuses to start if any enabled feature (embeddings/enrichment/rerank/HyDE) would
-  egress beyond the tier, and it installs a **deny-by-default runtime egress guard** on
-  the in-process network paths (`net`/`tls` sockets, `http(s)`, `fetch`) so even an
-  accidental call is blocked — turning "we don't call out" into "we *can't*."
-  `idx-index --attest` prints a deterministic attestation manifest (optionally
-  Ed25519/RSA-**signed** and CI-verifiable) of the egress posture. See `seal.mjs`.
-- **No code execution.** Source files are parsed into ASTs with Tree-sitter. The
-  indexer never imports, evaluates, or runs the code it indexes. The one subprocess
-  it spawns is a local, read-only `git log` (see "git signals" below) — never the
-  indexed code.
-- **Local git signals.** At index time the indexer optionally reads the repository's
-  *local* commit log (`git log` on `MCP_PROJECT_ROOT`) to derive churn / recency /
-  co-change ranking hints. No remote is contacted and no source content leaves the
-  machine — only commit metadata (paths, timestamps) is read locally. Disable it
-  entirely with `INDEXER_GIT_SIGNALS=off`, `--no-git-signals`, or
-  `"gitSignals": false`.
-- **Path-traversal guard.** The `get_file_skeleton` MCP tool resolves and normalizes
-  the requested path and rejects anything outside `MCP_PROJECT_ROOT`. Beyond the
-  textual check it also resolves symlinks with `realpath` on both the root and the
-  target and re-verifies containment, so a symlink *inside* the project that points
-  outside it cannot be used to read arbitrary files on the host.
-- **Local artifacts only.** The index (`code-index.json`) and embeddings
-  (`code-index.embeddings.bin`) are written inside the project and are git-ignored by
-  `init`. They contain snippets of your source code — treat them with the same
-  sensitivity as the repository itself and do not commit or share them.
-- **MCP transport.** The server communicates over stdio with the local MCP client
-  (your IDE/agent). It does not open a network socket.
-- **Taint analysis is advisory, not a guarantee.** The opt-in `trace_taint` /
-  `find_tainted_sinks` MCP tools statically trace untrusted sources to dangerous sinks
-  over the call graph using pure regex catalogs + graph traversal (no model, no network,
-  read-only). They are a **finder, not a verifier**: they favour precision and miss flows
-  through dynamic dispatch, reflection, ORM/query-builder indirection, and untyped
-  collections — **"0 findings" is not proof of safety.** Use them for orientation, not as
-  a security gate.
+- **No network.** graph-indexer makes no outbound connections: no telemetry, no model
+  downloads, no grammar installs. The tree-sitter runtime and all grammars ship inside the
+  package as WebAssembly (versions and SHA-256 checksums in `vendor/grammars/manifest.json`),
+  so there is no install-time or first-run download and no native build step.
+- **No dependencies.** The package has no npm dependencies; it uses only Node.js built-ins
+  (`node:sqlite`, `node:fs`, `node:child_process`, …) and the vendored WebAssembly runtime.
+- **No code execution.** Source files are parsed into syntax trees; the indexed code is never
+  imported, evaluated or run. The only subprocesses are read-only git commands
+  (`git rev-parse`, `git ls-files`, `git diff`, `git log`, `git show`) run in the indexed repository
+  with fixed arguments. The only tool input they take is the `base` revision of `check_changes`,
+  which is refused when git could read it as an option. Every git call switches off what the
+  repository's own git config could run: `core.fsmonitor`, hooks, signature verification,
+  clean/smudge/process filters, `diff.external` and textconv drivers.
+- **No code from the repository through npx.** Every `npx` command graph-indexer runs or writes into
+  an agent's configuration passes `--prefix`, so a `node_modules/graph-indexer` that the repository
+  ships is never run in place of the published package.
+- **Stays inside the repository.** Only files listed by git (or found by a `.gitignore`-aware
+  walk) under the repository root are indexed. Symlinks are followed only when their target
+  resolves inside the repository, so a link to a file elsewhere on the machine is never read,
+  indexed or served. Paths given to the tools (`read_code "file.ts:42"`, `outline`,
+  `change_impact`) are resolved (`..` and symbolic links) and must stay inside the repository;
+  `.git/` and `.graph-indexer/` are never served. Manifests (`package.json`, `tsconfig.json`,
+  `go.mod`) are read only as small regular files inside the repository.
+- **Bounded work.** A regular expression given to `search_text` runs under a 5 s budget, and a file
+  whose syntax makes the structural queries super-linear is given up after 15 s, so neither can
+  block the server.
+- **Read-only tools.** All MCP tools are read-only (`readOnlyHint: true`) and never modify
+  the repository.
+- **stdio transport.** The MCP server talks to the local client over stdin/stdout. It does not
+  open a network socket.
+- **Local socket for hooks and the CLI.** The MCP server, or `graph-indexer daemon` started by the
+  hooks, also answers hook and CLI queries over a Unix domain socket (a named pipe on Windows),
+  never TCP. The socket lives in `<repo>/.graph-indexer/` with mode 0600; when that path is too
+  long for a socket, in a per-user directory in the temp dir with mode 0700 whose owner and mode
+  both sides check before using it. It answers the same read-only queries as the CLI.
+  `GRAPH_INDEXER_RESIDENT=0` disables it.
+- **Local artifacts.** The index is a SQLite database in `<repo>/.graph-indexer/` (git-ignored by
+  `init`, mode 0700; a `.graph-indexer` that is a symbolic link is refused). It contains excerpts of your source code — treat it with the same sensitivity as the
+  repository itself and do not commit or share it. Deleting the directory is always safe; it is
+  rebuilt on the next run.
+
+## Runtime
+
+graph-indexer runs in the Node.js the user installs. It requires a release that includes the
+October 2026 Node.js security fixes (22.23.4+, 24.22.1+ or 26.12.1+; CVE-2026-111497 and others).
+Keep Node.js updated to the latest patch release of a supported line.
 
 ## Operational guidance
 
-- Point `MCP_PROJECT_ROOT` only at repositories you trust and intend to index.
-- If you set `OLLAMA_HOST` to a remote host, that host will receive code snippets as
-  embedding input — only do so on a network and host you control.
-- The background watch daemon respects `.gitignore` and skips `node_modules`, build
-  output, and dot-directories, so secrets in ignored paths are not indexed. Keep
-  sensitive files git-ignored.
+- Run the server only on repositories you trust and intend to index.
+- Keep secrets out of indexed source files (graph-indexer indexes what git tracks or what a
+  `.gitignore`-aware walk finds; ignored paths, `node_modules`, build output and dot-directories
+  are skipped).

package/bin/graph-indexer.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/**
+ * graph-indexer CLI.
+ *
+ *   graph-indexer serve   [--repo DIR]                MCP server on stdio (what agents launch)
+ *   graph-indexer index   [--repo DIR]                build / update the index and print stats
+ *   graph-indexer init    [--repo DIR] [--agents …]   wire the MCP server into your coding agents
+ *   graph-indexer status  [--repo DIR]
+ *   graph-indexer search   <query>  [--path P] [--kind K] [--limit N]
+ *   graph-indexer read     <target>… [--full]           symbols, file:START-END ranges or files, with the
+ *                                                        definitions each one uses
+ *   graph-indexer symbol   <name>…  [--no-code]
+ *   graph-indexer refs     <name>   [--kind K] [--path P] [--no-tests] [--limit N]
+ *   graph-indexer callgraph <name>  [--direction callers|callees|both] [--depth N] [--no-tests]
+ *   graph-indexer impact   [--symbols a,b] [--files x,y] [--diff] [--depth N]
+ *   graph-indexer outline  [path]   [--focus TEXT] [--max-tokens N]
+ *   graph-indexer files    <text|glob> [--path P]
+ *
+ * The query commands print exactly what the MCP tools return, so humans (and agents limited to a
+ * shell) get the same answers.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(fs.readFileSync(path.join(here, '..', 'package.json'), 'utf8'));
+
+const argv = process.argv.slice(2);
+const aliasOf = { 'idx-mcp': 'serve', 'idx-index': 'index', mcp: 'serve', references: 'refs', 'call-graph': 'callgraph', map: 'outline' };
+const invokedAs = path.basename(process.argv[1] || '').replace(/\.m?js$/, '');
+let cmd = aliasOf[invokedAs] ?? null;
+if (!cmd && argv.length && !argv[0].startsWith('-')) { const c = argv.shift(); cmd = aliasOf[c] ?? c; }
+
+function flag(name) { const i = argv.indexOf(name); if (i < 0) return false; argv.splice(i, 1); return true; }
+function opt(name, dflt = null) {
+    const i = argv.indexOf(name);
+    if (i < 0) return dflt;
+    const v = argv[i + 1];
+    argv.splice(i, 2);
+    return v;
+}
+
+const log = (m) => process.stderr.write(`[graph-indexer] ${m}\n`);
+// global options are consumed before any command joins the remaining words into a query
+const repoArg = opt('--repo') ?? process.env.GRAPH_INDEXER_REPO ?? process.env.MCP_PROJECT_ROOT ?? null;
+
+async function openIntel({ watch = false, background = false, quiet = false } = {}) {
+    const { CodeIntel } = await import('../src/query/intel.mjs');
+    const { findRepoRoot } = await import('../src/util/paths.mjs');
+    const root = repoArg ? path.resolve(repoArg) : findRepoRoot(process.cwd());
+    const intel = new CodeIntel({ root, log, watch });
+    let last = 0;
+    const onProgress = quiet ? null : (d, n) => {
+        const now = Date.now();
+        if (now - last > 1000 || d === n) { last = now; process.stderr.write(`\r[graph-indexer] indexing ${d}/${n} files`); if (d === n) process.stderr.write('\n'); }
+    };
+    await intel.open({ onProgress, background });
+    return intel;
+}
+
+/** Options left over after a command took its own are typos, not part of the query. */
+function rejectUnknownOptions() {
+    const bad = argv.filter(a => /^--?[A-Za-z][\w-]*$/.test(a));
+    if (!bad.length) return false;
+    process.stderr.write(`Unknown option${bad.length > 1 ? 's' : ''} for "${cmd}": ${bad.join(' ')}\n\n${HELP}\n`);
+    process.exitCode = 2;
+    return true;
+}
+
+async function runTool(name, args) {
+    return runTools([[name, args]]);
+}
+
+/** Several tool calls against one open index (e.g. `symbol A B C`), outputs separated by a blank line. */
+async function runTools(calls) {
+    if (rejectUnknownOptions()) return;
+    // a resident process (MCP server or daemon) answers without opening and syncing the index again
+    const { findRepoRoot } = await import('../src/util/paths.mjs');
+    const { askResident, residentRequired } = await import('../src/cli/resident.mjs');
+    const root = repoArg ? path.resolve(repoArg) : findRepoRoot(process.cwd());
+    const reply = await askResident(root, { op: 'tool', calls }, { version: pkg.version, totalMs: 60_000 });
+    if (reply && typeof reply.out === 'string') { process.stdout.write(reply.out + '\n'); return; }
+    if (residentRequired()) { process.stderr.write('graph-indexer: no resident process answers for this repository\n'); process.exitCode = 3; return; }
+    const intel = await openIntel({ quiet: true });
+    const { callTool } = await import('../src/mcp/tools.mjs');
+    try {
+        const outs = [];
+        for (const [name, args] of calls) outs.push(await callTool(intel, name, args, { cli: true }));
+        process.stdout.write(outs.join('\n\n') + '\n');
+    } finally { intel.close(); }
+}
+
+/**
+ * Answer hooks and CLI queries for this index over the repository's local socket (see
+ * src/cli/resident.mjs). Resolves to null when another process already does.
+ */
+async function serveResident(intel, { idleMs = 0, onIdle = null } = {}) {
+    const { startResident } = await import('../src/cli/resident.mjs');
+    const hold = async () => ({ intel, release() {} });
+    return startResident({
+        root: intel.root, version: pkg.version, log, idleMs, onIdle,
+        wanted: () => fs.existsSync(intel.dbPath),
+        handle: async (req) => {
+            if (req.op === 'hook') {
+                const { handleHook } = await import('../src/cli/hook.mjs');
+                return handleHook(String(req.event ?? ''), req.input ?? {}, { root: intel.root, acquire: hold });
+            }
+            if (req.op === 'tool' && Array.isArray(req.calls)) {
+                const { callTool } = await import('../src/mcp/tools.mjs');
+                const outs = [];
+                for (const [name, args] of req.calls) outs.push(await callTool(intel, name, args ?? {}, { cli: true }));
+                return outs.join('\n\n');
+            }
+            return null;
+        },
+    });
+}
+
+const HELP = `graph-indexer ${pkg.version} — live code graph & search for AI coding agents (MCP)
+
+Usage:
+  graph-indexer init [--repo DIR] [--agents claude,cursor,vscode,gemini,codex,opencode,junie,zed,devin] [--all] [--hooks] [--local] [--dry-run] [--no-instructions] [--no-helper]
+  graph-indexer serve [--repo DIR]          start the MCP server on stdio
+  graph-indexer index [--repo DIR]          build or update the index
+  graph-indexer status [--repo DIR]
+  graph-indexer search <query> [--path P] [--kind K] [--limit N]
+  graph-indexer grep <regex> [--path P] [--literal|-F] [-i] [--limit N]
+  graph-indexer files <text|glob> [--path P] [--limit N]    find files by path or name
+  graph-indexer read <target>… [--full] [--max-lines N]   symbols (Class.method), ranges (file:10-80) or files,
+                                                   with where each name they use is defined
+  graph-indexer symbol <name>… [--no-code]         one or several definitions
+  graph-indexer refs <name> [--kind call|type|inherit|new|value|decorator] [--path P] [--no-tests]
+  graph-indexer callgraph <name> [--direction callers|callees|both] [--depth N] [--no-tests]
+  graph-indexer impact [--symbols a,b] [--files x,y] [--diff] [--depth N]
+  graph-indexer outline [path] [--focus TEXT] [--max-tokens N]
+  graph-indexer check [--files x,y] [--base REV]     verify uncommitted edits
+  graph-indexer hook post-tool|session-start|subagent-start   agent hook (JSON on stdin)
+  graph-indexer daemon [--idle-minutes N]           keep the index open for hooks and CLI queries
+                                                   (the hooks start it; the MCP server does the same)
+
+The index lives in <repo>/.graph-indexer/ and is kept in sync automatically.`;
+
+async function main() {
+    if (!cmd || cmd === 'help' || flag('--help') || flag('-h')) { process.stdout.write(HELP + '\n'); return; }
+    if (cmd === 'version' || flag('--version')) { process.stdout.write(pkg.version + '\n'); return; }
+    switch (cmd) {
+        case 'serve': {
+            const intel = await openIntel({ watch: true, background: true, quiet: true });
+            const { McpServer } = await import('../src/mcp/server.mjs');
+            const server = new McpServer({ intel, version: pkg.version, log, ready: intel.ready });
+            intel.ready.then((r) => log(`index ready: ${r.total} files (${r.added} added, ${r.changed} changed, ${r.removed} removed) in ${r.ms} ms`)).catch((e) => log(`indexing failed: ${e.stack || e.message}`));
+            server.onClose = () => { intel.close(); process.exit(0); };
+            server.listen();
+            for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => { intel.close(); process.exit(0); });
+            serveResident(intel).catch((e) => log(`resident: ${e.message}`));
+            return;
+        }
+        case 'daemon': {
+            // the resident for hooks and CLI queries when no MCP server runs; the hooks start it
+            const idle = Math.max(1, Number(opt('--idle-minutes', 30)));
+            const { findRepoRoot } = await import('../src/util/paths.mjs');
+            const { askResident } = await import('../src/cli/resident.mjs');
+            const root = repoArg ? path.resolve(repoArg) : findRepoRoot(process.cwd());
+            if (await askResident(root, { op: 'ping' }, { version: pkg.version })) return; // already served
+            const intel = await openIntel({ watch: true, quiet: true });
+            const stop = () => { intel.close(); process.exit(0); };
+            const res = await serveResident(intel, { idleMs: idle * 60_000, onIdle: stop });
+            if (!res) { intel.close(); return; }
+            for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, stop);
+            return;
+        }
+        case 'index': {
+            const t0 = Date.now();
+            const intel = await openIntel();
+            const st = intel.stats();
+            const r = intel.lastSyncStats;
+            process.stdout.write(`indexed ${st.root}\n  ${st.files} files · ${st.symbols} symbols · ${st.refs} references (${st.resolved} resolved, ${st.exact} exact)\n  this run: ${r.added} added, ${r.changed} changed, ${r.removed} removed in ${Date.now() - t0} ms\n  languages: ${st.langs.map(l => `${l.lang} ${l.n}`).join(', ')}\n`);
+            intel.close();
+            return;
+        }
+        case 'status': {
+            const intel = await openIntel({ quiet: true });
+            const st = intel.stats();
+            process.stdout.write(JSON.stringify({ version: pkg.version, ...st, db: intel.dbPath }, null, 2) + '\n');
+            intel.close();
+            return;
+        }
+        case 'init': {
+            const { runInit } = await import('../src/cli/init.mjs');
+            await runInit({ argv, opt, flag, log, version: pkg.version, repo: repoArg });
+            return;
+        }
+        case 'search': {
+            const pathF = opt('--path'); const kind = opt('--kind'); const limit = Number(opt('--limit', 8));
+            return runTool('search_code', { query: argv.join(' '), path: pathF, kind, limit });
+        }
+        case 'grep': {
+            const pathF = opt('--path'); const literal = flag('--literal') || flag('-F'); const ic = flag('-i') || flag('--ignore-case'); const limit = Number(opt('--limit', 60));
+            const pattern = argv.shift();
+            return runTool('search_text', { pattern, path: pathF, literal, ignore_case: ic, limit });
+        }
+        case 'read': {
+            const full = flag('--full'); const maxLines = Number(opt('--max-lines', 200));
+            const targets = argv.filter(a => !a.startsWith('--'));
+            argv.length = 0;
+            return runTool('read_code', { targets, full, max_lines: maxLines });
+        }
+        case 'symbol': {
+            const noCode = flag('--no-code'); const maxLines = Number(opt('--max-lines', 200));
+            // `symbol A B C` reads several definitions in one call
+            const targets = argv.filter(a => !a.startsWith('--'));
+            return runTools((targets.length ? targets : ['']).map(t => ['get_symbol', { symbol: t, include_code: !noCode, max_lines: maxLines }]));
+        }
+        case 'refs': {
+            const kind = opt('--kind', 'all'); const noTests = flag('--no-tests'); const limit = Number(opt('--limit', 80)); const pathF = opt('--path');
+            return runTool('find_references', { symbol: argv.join(' '), kind, include_tests: !noTests, limit, ...(pathF ? { path: pathF } : {}) });
+        }
+        case 'callgraph': {
+            const direction = opt('--direction', 'both'); const depth = Number(opt('--depth', 2)); const limit = Number(opt('--limit', 40)); const noTests = flag('--no-tests');
+            return runTool('call_graph', { symbol: argv.join(' '), direction, depth, limit, include_tests: !noTests });
+        }
+        case 'impact': {
+            const symbols = (opt('--symbols') ?? '').split(',').filter(Boolean);
+            const files = (opt('--files') ?? '').split(',').filter(Boolean);
+            const diff = flag('--diff'); const depth = Number(opt('--depth', 3));
+            return runTool('change_impact', { symbols, files, diff, depth });
+        }
+        case 'hook': {
+            const { runHook } = await import('../src/cli/hook.mjs');
+            return runHook(argv.shift() ?? '', { repo: repoArg, version: pkg.version });
+        }
+        case 'check': {
+            const files = (opt('--files') ?? '').split(',').filter(Boolean); const base = opt('--base', 'HEAD');
+            return runTool('check_changes', { files, base });
+        }
+        case 'files': {
+            const pathF = opt('--path'); const limit = Number(opt('--limit', 100));
+            return runTool('find_files', { pattern: argv.join(' '), path: pathF, limit });
+        }
+        case 'outline': {
+            const focus = opt('--focus'); const maxTokens = Number(opt('--max-tokens', 1500));
+            return runTool('outline', { path: argv[0] ?? '', focus, max_tokens: maxTokens });
+        }
+        default:
+            process.stderr.write(`Unknown command: ${cmd}\n\n${HELP}\n`);
+            process.exitCode = 2;
+    }
+}
+
+main().catch((e) => { process.stderr.write(`graph-indexer: ${e.stack || e.message}\n`); process.exit(1); });

package/integrations/claude-code/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "graph-indexer",
+  "version": "3.0.1",
+  "description": "Live code graph for Claude Code: exact references, structural grep, change impact and a post-edit check, from a local index with no model or network.",
+  "author": { "name": "MaquinaTech", "url": "https://github.com/MaquinaTech" },
+  "homepage": "https://github.com/MaquinaTech/graph-indexer",
+  "license": "MIT",
+  "icon": "https://raw.githubusercontent.com/MaquinaTech/graph-indexer/main/assets/logo.jpg"
+}

package/integrations/claude-code/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "graph-indexer": {
+      "command": "npx",
+      "args": ["-y", "--prefix", "/", "graph-indexer@3.0.1", "serve"]
+    }
+  }
+}

package/integrations/claude-code/agents/code-structure.md

@@ -0,0 +1,22 @@
+---
+name: code-structure
+description: "Exact answers to structural questions about this repository's code, from graph-indexer's index, on a small fast model: every call site of a function or method (told apart from same-name methods of other classes), callers of callers, classes that extend or implement a type, and what a change would affect with the tests that cover it. Give it the symbol (Class.method, with its file when you know it) and the scope (directories, whether tests count, how many levels); it replies with path:line lists and says whether they are complete. Delegate these instead of grepping for names and reading files yourself."
+model: haiku
+disallowedTools: Edit, Write, MultiEdit, NotebookEdit
+omitClaudeMd: true
+---
+You answer structural questions about the code in this repository — where something is used, who calls it, what extends or implements it, what a change would affect — exactly and briefly, from graph-indexer's index (the graph-indexer tools). The index binds every reference through scopes, imports and receiver types, so methods that only share a name are kept apart, and it re-syncs with the files before every answer.
+
+How to answer
+- Call sites or other uses of a function, method or class: `find_references` on it (`Class.method`, or `path:Name` when the name is ambiguous), with kind `call` for calls only, `include_tests: false` when tests are excluded and `path` for one directory. It says when the list is complete.
+- Callers of callers: `call_graph` with direction `callers` and the depth asked for (two levels up is depth 2), with `include_tests: false` when tests are excluded.
+- Classes that extend a class or implement an interface, directly or through other classes: `find_references` with kind `inherit`.
+- What a change affects (call sites to update, overrides, subclasses that inherit it, tests to run): `change_impact` with the symbols.
+- A definition or a signature: `read_code` with its name.
+- Answer from these results. Read code or search text only to settle what they report as unresolved or incomplete (a call through a name built at run time, a receiver of unknown type), not to redo a list they give as complete.
+- Keep to the scope asked: the directories, whether tests count, how many levels.
+
+Reply
+- When the request gives an answer format, follow it exactly.
+- Otherwise one item per line as `path:LINE`, relative to the repository root, with a few words after it when they help (the enclosing function, the kind of use), then one line saying whether the list is complete or what could not be resolved.
+- Nothing else: no account of how you found it. You do not change files.

package/integrations/claude-code/hooks/gi-hook.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * The plugin's hook command: hands the hook payload to the graph-indexer resident process of the
+ * repository (the plugin's MCP server keeps one running) and prints its answer.
+ *
+ * Starting graph-indexer through `npx` costs about a second on every call; this client only
+ * connects to a local socket (tens of milliseconds). When no resident answers, it runs the full
+ * hook through npx once, which also starts a resident for the next calls.
+ *
+ *   node gi-hook.mjs post-tool|session-start|subagent-start   (hook payload on stdin)
+ *
+ * The socket location must match socketPath() in graph-indexer's src/cli/resident.mjs.
+ */
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+
+const PROTOCOL = 1;
+const WIN = process.platform === 'win32';
+
+export function findRepoRoot(start) {
+    let dir = path.resolve(start);
+    for (;;) {
+        if (fs.existsSync(path.join(dir, '.git'))) return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir) return path.resolve(start);
+        dir = parent;
+    }
+}
+
+export function socketPath(root) {
+    const abs = path.resolve(root);
+    const hash = crypto.createHash('sha256').update(abs).digest('hex').slice(0, 16);
+    if (WIN) return `\\\\.\\pipe\\graph-indexer-${hash}`;
+    const inRepo = path.join(abs, '.graph-indexer', 'resident.sock');
+    if (Buffer.byteLength(inRepo) <= 100) return inRepo;
+    return path.join(os.tmpdir(), `graph-indexer-${process.getuid?.() ?? 'user'}`, `${hash}.sock`);
+}
+
+function trusted(file, root) {
+    if (WIN) return true;
+    const mine = (st) => !process.getuid || st.uid === process.getuid();
+    try {
+        const sock = fs.lstatSync(file), dir = fs.lstatSync(path.dirname(file));
+        const inRepo = path.dirname(file) === path.join(path.resolve(root), '.graph-indexer');
+        // the socket and its directory are ours, not links or listeners planted by the repository or another user
+        return sock.isSocket() && mine(sock) && dir.isDirectory() && mine(dir) && (inRepo || (dir.mode & 0o077) === 0);
+    } catch { return false; }
+}
+
+/** The resident's answer ({ out }) or null. `any: true`: this client has no logic of its own to match. */
+function ask(root, request, totalMs) {
+    const file = socketPath(root);
+    if (!trusted(file, root)) return Promise.resolve(null);
+    return new Promise((resolve) => {
+        let done = false, buf = '';
+        const sock = net.createConnection(file);
+        const finish = (v) => { if (!done) { done = true; clearTimeout(timer); sock.destroy(); resolve(v); } };
+        const timer = setTimeout(() => finish(null), totalMs);
+        sock.setEncoding('utf8');
+        sock.on('connect', () => sock.write(JSON.stringify({ v: PROTOCOL, any: true, ...request }) + '\n'));
+        sock.on('data', (d) => {
+            buf += d;
+            const i = buf.indexOf('\n');
+            if (i < 0) return;
+            let r = null;
+            try { r = JSON.parse(buf.slice(0, i)); } catch { /* garbled */ }
+            finish(r?.ok ? r : null);
+        });
+        sock.on('error', () => finish(null));
+        sock.on('close', () => finish(null));
+    });
+}
+
+async function main() {
+    const event = process.argv[2] ?? '';
+    const chunks = [];
+    if (!process.stdin.isTTY) for await (const c of process.stdin) chunks.push(c);
+    const raw = Buffer.concat(chunks).toString('utf8');
+    let input = {};
+    try { input = JSON.parse(raw || '{}'); } catch { return; }
+    const root = findRepoRoot(input.cwd || process.cwd());
+    const reply = await ask(root, { op: 'hook', event, input }, 2500);
+    if (reply) { if (reply.out) process.stdout.write(reply.out + '\n'); return; }
+    // no resident yet: the full hook through npx (it starts one for the next calls); --prefix keeps
+    // npx from running a graph-indexer that the repository ships in its own node_modules
+    // (on Windows npx.cmd needs a shell, so the home directory is quoted for cmd.exe)
+    const home = WIN ? `"${os.homedir()}"` : os.homedir();
+    const child = spawn(WIN ? 'npx.cmd' : 'npx', ['-y', '--prefix', home, 'graph-indexer@3', 'hook', event], { stdio: ['pipe', 'inherit', 'ignore'], shell: WIN });
+    child.on('error', () => { /* fail open */ });
+    child.stdin.on('error', () => { /* fail open */ });
+    child.stdin.end(raw);
+    await new Promise((resolve) => child.on('close', resolve).on('error', resolve));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    const timer = setTimeout(() => process.exit(0), 9000); // fail open before the host's 10 s timeout
+    main().catch(() => { /* fail open */ }).finally(() => clearTimeout(timer));
+}

package/integrations/claude-code/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit|Grep|Bash|Read",
+        "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gi-hook.mjs\" post-tool", "timeout": 10 }]
+      }
+    ],
+    "SessionStart": [
+      { "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gi-hook.mjs\" session-start", "timeout": 10 }] }
+    ],
+    "SubagentStart": [
+      { "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gi-hook.mjs\" subagent-start", "timeout": 10 }] }
+    ]
+  }
+}