graph-indexer 3.0.0 → 3.1.0

package/README.md

@@ -9,7 +9,7 @@
 
   <a href="https://www.npmjs.com/package/graph-indexer"><img src="https://img.shields.io/npm/v/graph-indexer?color=007acc&style=for-the-badge" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/graph-indexer"><img src="https://img.shields.io/npm/dt/graph-indexer?color=4caf50&style=for-the-badge" alt="NPM Downloads"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-%3E%3D22.5-brightgreen?style=for-the-badge&logo=nodedotjs" alt="Node.js 22.5+"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-22.23.4%2B%20%7C%2024.22.1%2B%20%7C%2026.12.1%2B-brightgreen?style=for-the-badge&logo=nodedotjs" alt="Node.js 22.23.4+, 24.22.1+ or 26.12.1+"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge" alt="License: MIT"></a>
 </div>
 
@@ -40,14 +40,18 @@ instead of reading whole files and grepping.
 
 ## Quick start
 
-Requires **Node.js 22.5+** (for the built-in `node:sqlite`).
+Requires **Node.js 22.23.4+, 24.22.1+ or 26.12.1+** (the built-in `node:sqlite`, and the October 2026
+Node.js security releases, which fix CVE-2026-111497).
 
 ```bash
 cd your-repo
-npx graph-indexer init      # wires the MCP server into the agents it detects
-npx graph-indexer index     # optional: build the index now (the server also does it on start)
+npx -y --prefix / graph-indexer@3 init    # wires the MCP server into the agents it detects
+npx -y --prefix / graph-indexer@3 index   # optional: build the index now (the server also does it on start)
 ```
 
+`--prefix /` makes npx run the published package even in a repository that ships its own
+`node_modules/graph-indexer`.
+
 `init` writes project-level MCP configuration for the agents it finds (`.mcp.json` for Claude
 Code, `.cursor/mcp.json`, `.vscode/mcp.json`, `.gemini/settings.json`, `opencode.json` for
 OpenCode and Kilo Code, `.junie/mcp/mcp.json`, `.zed/settings.json`; it prints the Codex TOML
@@ -56,12 +60,18 @@ to `.gitignore`, and adds a short block to `CLAUDE.md` / `AGENTS.md` on how to l
 For Claude Code it also writes a structural helper, `.claude/agents/code-structure.md`: a
 read-only sub-agent on a small model that answers call-site, caller, subclass and impact
 questions from the index, so the main agent can hand them off and get back only the list (the
-Claude Code plugin ships it too). `--hooks` adds the Claude Code hooks to `.claude/settings.json`,
+Claude Code plugin ships it too (`integrations/claude-code`; the full plugin with hooks is `integrations/claude-code-local`)). `--hooks` adds the Claude Code hooks to `.claude/settings.json`,
 which Devin, Copilot CLI and Cursor also run, and the OpenCode / Kilo Code plugin that appends the
 same context to their tool output. Flags: `--agents claude,cursor,vscode,gemini,codex,opencode,junie,zed,devin`,
 `--all`, `--hooks`, `--local` (use this checkout instead of `npx`), `--dry-run`,
 `--no-instructions`, `--no-helper`.
 
+In Claude Code (2.1.275 or later), the plugin installs in one step:
+
+```text
+/plugin install graph-indexer --marketplace MaquinaTech/graph-indexer
+```
+
 <details>
 <summary>Manual configuration</summary>
 
@@ -70,7 +80,7 @@ Any MCP client can run the server over stdio:
 ```json
 {
   "mcpServers": {
-    "graph-indexer": { "command": "npx", "args": ["-y", "graph-indexer@3", "serve", "--repo", "/path/to/repo"] }
+    "graph-indexer": { "command": "npx", "args": ["-y", "--prefix", "/", "graph-indexer@3", "serve", "--repo", "/path/to/repo"] }
   }
 }
 ```
@@ -81,7 +91,7 @@ VS Code uses `"servers"` instead of `"mcpServers"` and `"type": "stdio"`. Codex
 ```toml
 [mcp_servers.graph-indexer]
 command = "npx"
-args = ["-y", "graph-indexer@3", "serve", "--repo", "/path/to/repo"]
+args = ["-y", "--prefix", "/", "graph-indexer@3", "serve", "--repo", "/path/to/repo"]
 ```
 
 Without `--repo` the server indexes the git repository containing its working directory
@@ -90,11 +100,19 @@ Without `--repo` the server indexes the git repository containing its working di
 
 ## The tools
 
+`npx graph-indexer init` ends with an example from your own repository: a method that shares its
+name with other definitions, what grep returns for that name, and the calls the index binds to
+that one definition (`npx graph-indexer demo` shows it again).
+
 | Tool | Use it to | Typical reply |
 |---|---|---|
+| `explore` | start a task or bug in code you have not read, in one call | the most relevant definitions with their code, who calls them, overrides and subclasses, where the names they use are defined and the tests to run with the command — inside a token budget, naming what it left out |
+| `explore` + routes | ask about an endpoint ("what happens on POST /owners/42/edit") | the handler the framework registers for it — FastAPI, Flask, NestJS, Spring, Express/Fastify/Koa/Hono, Gin/Echo/chi; `npx graph-indexer routes` lists them all |
+| dependency injection | look up a NestJS or Spring class, interface or token (`find_references`, `explore`) | what an injection point receives — NestJS: the `provide: TOKEN, useClass/useFactory/…` or `ClientsModule` registration of an `@Inject(TOKEN)`; Spring: the bean of an `@Autowired`/constructor/`@Bean` parameter, chosen by `@Qualifier`, `@Primary` and name, Feign, Spring Data and MyBatis proxies named as such — and where a provider is injected, which neither the type checker nor grep for the type connects; `npx graph-indexer inject` lists them all |
+| ORM models | look up a model (`find_references`, `explore`; `npx graph-indexer models`) | its table, the migrations that touch it, and for Prisma the client calls (`prisma.user.findMany`) that only the generated client types — Prisma, Django, SQLAlchemy/SQLModel, TypeORM |
 | `read_code` | read symbols, line ranges or files — several per call — without searching for what they use | code with line numbers, then where each name it uses is defined (file:line and signature); who uses a symbol and which tests reference it; a long file's outline |
 | `search_text` | grep any text across the repository (code, config, docs) | grep lines with the enclosing definition and, for identifiers, the definition each match refers to; where the definition is when the search missed it |
-| `search_code` | find where a behaviour or identifier lives (natural language or names) | ranked symbols with location, signature, doc line and matching lines |
+| `search_code` | find where a behaviour or identifier lives (natural language or names); `queries: [...]` asks for several phrasings at once | ranked symbols with location, signature, doc line and matching lines; for a question about docs, design or the reason for something, the Markdown sections that answer it |
 | `find_references` | see every use before renaming or changing a signature | uses grouped by file, enclosing function, confidence, calls through base types marked |
 | `call_graph` | trace callers and callees across files | a tree with locations and confidence |
 | `change_impact` | get the blast radius of a change, or of your uncommitted diff | transitive dependents by distance, tests to run, co-changed files, risk |
@@ -132,6 +150,12 @@ often changed together (git): context.go (14/42), context_test.go (10/42), …
 risk: medium (9 dependents, 1 test files)
 ```
 
+**Search by meaning (optional).** `npx graph-indexer semantic install` downloads a 32 MB static code
+embedding model (potion-code-16M-v2, MIT, pinned and checksummed); with `GRAPH_INDEXER_SEMANTIC=1`
+search also ranks definitions by meaning, in plain JavaScript and without network access. It helps
+queries written in words (top-5 success 0.674 → 0.728) and not the localization of real commits,
+so it is off by default ([measurements](docs/BENCHMARKS.md#3-symbol-search)).
+
 Every reference carries a confidence: **exact/high** means it was bound through a scope,
 import or inferred receiver type; **likely/possible** means only the name matched. Footers
 report same-name call sites that could not be bound, so an agent knows when to double-check
@@ -157,8 +181,10 @@ own `findReferences` (import lines and declarations excluded):
 do not. Against the compiler's full rename set (sibling overrides included) recall is 0.925. The
 fixture has no `node_modules`, so library-typed values are invisible to the compiler: precision is
 a lower bound.* The same measurement against the Go type checker (gin, caddy, nats-server) gives
-precision 0.992–1.000 and recall 0.972–0.981, and against the Java compiler (spring-petclinic,
-jsoup, Commons Collections) 0.955–0.994 and 0.861–0.989; grep's precision there is 0.02–0.61.
+precision 0.992–1.000 and recall 0.972–0.981, against the Java compiler (spring-petclinic,
+jsoup, Commons Collections) 0.961–0.994 and 0.883–0.989, against pyright (six Python
+repositories) 0.895–0.998 and 0.927–0.998, and against rust-analyzer (serde_json, ripgrep, tokio)
+0.968–0.990 and 0.799–0.942; grep's precision there is 0.01–0.61.
 In the server of Twenty, an open-source CRM monorepo (28,512 files), precision is 0.999 and
 recall 0.924; grep's precision is 0.009 and 2.x's 0.052.
 
@@ -168,7 +194,7 @@ rolled back to the parent commit first.
 
 | | file Acc@1 | file Acc@5 | function Acc@5 | function MRR@10 |
 |---|---|---|---|---|
-| graph-indexer `search_code` | **0.544** | **0.805** | **0.528** | **0.432** |
+| graph-indexer `search_code` | **0.550** | **0.799** | **0.528** | **0.433** |
 | grep, files ranked by idf-weighted hits | 0.485 | 0.769 | 0.514 | 0.374 |
 | BM25 over the same index | 0.373 | 0.722 | 0.401 | 0.290 |
 
@@ -176,6 +202,14 @@ rolled back to the parent commit first.
 strictly at symbol level: rank-1 0.703 and MRR 0.760, against 0.552 and 0.646 for graph-indexer
 2.x on the same queries. On the 169 held-out queries (never used for tuning) MRR is 0.773 vs 0.632.
 
+**Against zvec-grep 0.3.0** (hybrid BM25 + vector search, with its default embedding model,
+Qwen3-Embedding-0.6B, run on the same Mac): on the same 377 queries its best setting, code only,
+reaches rank-1 0.581 and MRR 0.639 (graph-indexer 0.703 and 0.761); on the 169 commits it puts
+the changed file first in 0.420 of them (graph-indexer 0.550, ranked grep 0.485). It is ahead on
+two repositories, gin and fastapi. It has no references or callers. In a one-repetition pilot of
+agent sessions (Haiku 5.5, 24 tasks, 13 of them from zvec-grep's own benchmark) neither tool beat
+Claude Code alone. [Details](docs/BENCHMARKS.md#zvec-grep-030-2026-11-06).
+
 **Against 2.x.** In real Claude Code sessions on nestjs and Twenty (40 tasks, 120 runs), 3.0
 cost 0.43 of 2.x on code questions and 0.46 on refactors, with a quarter to a third of the
 tokens spent looking code up; 2.x cost about twice as much as no index, as its tools and prompt
@@ -236,9 +270,32 @@ files are re-parsed. Warm tool calls take 1–4 ms for the graph tools, about 30
 
 ## Languages
 
-JavaScript, TypeScript/TSX, Python, Go, Java, Kotlin, Scala, C#, Rust, C, C++, Ruby, PHP, Bash
-and CSS/SCSS/Less. Reference binding and type inference are deepest for TypeScript/JavaScript,
-Python, Go, Java, C# and Rust.
+Every language gets definitions, outlines, search and edit checks. How far references are bound
+differs, and is stated rather than implied:
+
+| Level | Languages | What it means |
+|---|---|---|
+| **Verified** | TypeScript/TSX, Go, Java, Python, Rust | references measured against the language's own compiler or type checker on three or more real repositories ([docs/BENCHMARKS.md](docs/BENCHMARKS.md)): TypeScript 0.997 precision / 0.962 recall (nestjs), Go ≥ 0.992 / ≥ 0.972 (gin, caddy, nats-server), Java 0.961–0.994 / 0.883–0.989 (spring-petclinic, jsoup, Commons Collections), Python 0.895–0.998 / 0.927–0.998 against pyright (fastapi, flask, requests, httpx, rich, click), Rust 0.974–0.990 / 0.838–0.947 against rust-analyzer (serde_json, ripgrep, tokio) |
+| **Resolved** | JavaScript, C#, Vue and Svelte components (`<script>` as TypeScript; template tags as uses of the components imported) | scopes, imports and receiver types inferred from declarations, annotations and constructors; no compiler oracle yet |
+| **Scoped** | Kotlin, Scala, C, C++, Ruby, PHP | scopes, imports/includes and packages; less type inference, so more calls stay unbound or by name |
+| **Symbols** | Bash, CSS/SCSS/Less | definitions, outlines and search; references by name |
+
+Each answer marks how a reference was bound (`exact`, `likely`, `possible`) and says when a list is
+complete, whatever the level.
+
+How much of the code the parser reads, measured on public repositories (68,000 files in 46
+repositories: the fixtures, the agent benchmark's repositories, okhttp, kotlinx.coroutines,
+nowinandroid, Exposed, spring-boot, cats, Play and Jellyfin):
+
+| | files with a region the parser cannot read |
+|---|---|
+| TypeScript, TSX, JavaScript, Python, Java, Kotlin, Scala, C#, Rust, Go, Ruby, PHP | 0–0.2% (test data with deliberate syntax errors, `typeof import()` in type arguments, Python 3.15 unpacking comprehensions) |
+| Bash | 4% (zsh completion scripts) |
+| C, C++ | 39% of files, 15% of lines: macros inside declarations (`void (CJSON_CDECL *fn)(…)`); the functions themselves are kept |
+| SCSS, Less | about half of the files: they are read with the CSS grammar, which does not know nesting, `#{…}` or mixins |
+
+Where a symbol's name occurs in code the parser could not read, `find_references` and
+`call_graph` say so and name the lines, instead of reporting the list as complete.
 
 ## Command line
 
@@ -276,7 +333,7 @@ Version 3 is a rewrite; see the [changelog](CHANGELOG.md). In short: the tools c
 `check_changes`, `outline`), the
 embedding, Ollama, reranker and daemon options are gone (search is lexical plus graph and needs
 no model), grammars are bundled instead of installed on first use, and Node.js 22.5+ is required.
-Re-run `npx graph-indexer init` to update agent configuration; old `.graph-indexer/` contents are
+Re-run `npx -y --prefix / graph-indexer@3 init` to update agent configuration; old `.graph-indexer/` contents are
 replaced automatically.
 
 ## License

package/SECURITY.md

@@ -33,13 +33,24 @@ graph-indexer is a local developer tool. Its threat model follows from a few del
   (`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`) run in the indexed repository with
-  fixed arguments; no tool input is passed to them.
+  (`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 looked up in the index, never opened directly from disk.
+  `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
@@ -51,10 +62,16 @@ graph-indexer is a local developer tool. Its threat model follows from a few del
   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`). It contains excerpts of your source code — treat it with the same sensitivity as the
+  `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
 
 - Run the server only on repositories you trust and intend to index.

package/bin/graph-indexer.mjs

@@ -6,7 +6,8 @@
  *   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 explore  <task in words> [--symbols a,b] [--path P] [--max-tokens N]
+ *   graph-indexer search   <query>  [--or 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]
@@ -15,6 +16,7 @@
  *   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]
+ *   graph-indexer demo                             grep versus exact uses, on this repository
  *
  * The query commands print exactly what the MCP tools return, so humans (and agents limited to a
  * shell) get the same answers.
@@ -33,6 +35,8 @@ 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; }
+/** Every value of a repeatable option (`--or a --or b`). */
+function opts(name) { const out = []; let v; while ((v = opt(name)) != null) out.push(v); return out; }
 function opt(name, dflt = null) {
     const i = argv.indexOf(name);
     if (i < 0) return dflt;
@@ -120,13 +124,21 @@ async function serveResident(intel, { idleMs = 0, onIdle = 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 init [--repo DIR] [--agents claude,cursor,vscode,gemini,codex,opencode,junie,zed,devin] [--all] [--hooks] [--local] [--dry-run] [--no-instructions] [--no-helper] [--no-demo]
   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 explore <task in words> [--or QUERY]… [--symbols a,b] [--path P] [--max-tokens N]
+                                                   relevant code, callers, definitions used and tests
+  graph-indexer search <query> [--or QUERY]… [--path P] [--kind K] [--limit N]
+                                                   --or: other phrasings of the same need, fused
   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 demo                               a method that shares its name: grep versus its exact uses
+  graph-indexer report                             summary to paste into an issue (no paths, names or code)
+  graph-indexer routes [path | METHOD /path]       HTTP routes and their handlers
+  graph-indexer inject [token | class]             dependency injection: tokens, providers, injection points
+  graph-indexer models [name | table]              ORM models: table, migrations, Prisma client calls
   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
@@ -136,6 +148,8 @@ Usage:
   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 semantic install|status        optional static code-embedding model (32 MB, MIT) for
+                                                   search in words; used with GRAPH_INDEXER_SEMANTIC=1
   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)
 
@@ -170,6 +184,17 @@ async function main() {
             for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, stop);
             return;
         }
+        case 'semantic': {
+            const { installModel, modelDir, semanticEnabled, MODEL } = await import('../src/search/semantic.mjs');
+            const sub = argv.shift() ?? 'status';
+            if (sub === 'install') {
+                const dir = await installModel({ log });
+                process.stdout.write(`${MODEL.repo}@${MODEL.revision.slice(0, 12)} (${MODEL.license}) installed in ${dir}\nTurn the semantic channel on with GRAPH_INDEXER_SEMANTIC=1.\n`);
+            } else {
+                process.stdout.write(JSON.stringify({ model: MODEL.repo, revision: MODEL.revision, dir: modelDir(), installed: fs.existsSync(path.join(modelDir(), 'model.safetensors')), enabled: semanticEnabled() }, null, 2) + '\n');
+            }
+            return;
+        }
         case 'index': {
             const t0 = Date.now();
             const intel = await openIntel();
@@ -191,9 +216,13 @@ async function main() {
             await runInit({ argv, opt, flag, log, version: pkg.version, repo: repoArg });
             return;
         }
+        case 'explore': {
+            const symbols = (opt('--symbols') ?? '').split(',').filter(Boolean); const pathF = opt('--path'); const maxTokens = Number(opt('--max-tokens', 2000)); const queries = opts('--or');
+            return runTool('explore', { query: argv.join(' '), queries, symbols, path: pathF, max_tokens: maxTokens });
+        }
         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 });
+            const pathF = opt('--path'); const kind = opt('--kind'); const limit = Number(opt('--limit', 8)); const queries = opts('--or');
+            return runTool('search_code', { query: argv.join(' '), queries, 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));
@@ -234,6 +263,18 @@ async function main() {
             const files = (opt('--files') ?? '').split(',').filter(Boolean); const base = opt('--base', 'HEAD');
             return runTool('check_changes', { files, base });
         }
+        case 'demo': return runTool('demo', {});
+        case 'routes': return runTool('routes', { filter: argv.join(' ') });
+        case 'inject': return runTool('inject', { filter: argv.join(' ') });
+        case 'models': return runTool('models', { filter: argv.join(' ') });
+        case 'report': {
+            // for bug reports: sizes, languages, binding rates and latencies — no paths, names or code
+            const intel = await openIntel({ quiet: true });
+            const { reportText } = await import('../src/query/report.mjs');
+            process.stdout.write(await reportText(intel, { version: pkg.version }) + '\n');
+            intel.close();
+            return;
+        }
         case 'files': {
             const pathF = opt('--path'); const limit = Number(opt('--limit', 100));
             return runTool('find_files', { pattern: argv.join(' '), path: pathF, limit });

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

@@ -1,8 +1,9 @@
 {
   "name": "graph-indexer",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "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"
+  "license": "MIT",
+  "icon": "https://raw.githubusercontent.com/MaquinaTech/graph-indexer/main/assets/logo.jpg"
 }

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

@@ -1,9 +1,6 @@
 ---
 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.
 

package/integrations/claude-code/skills/setup/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: setup
+description: Connect graph-indexer's MCP server to this repository so Claude Code can use exact references, call graphs and change impact. Use when the user installs this plugin, or when the graph-indexer tools (find_references, call_graph, change_impact) are not available.
+---
+# Connect graph-indexer
+
+This plugin brings the `code-structure` sub-agent and these instructions. The graph-indexer tools
+come from a local MCP server that the user adds to the repository once. The plugin directory does not
+allow plugins to start local programs, so the user must approve this step.
+
+1. Check that Node.js 22.23.4+, 24.22.1+ or 26.12.1+ is installed (`node --version`).
+2. Ask the user to confirm, then run from the repository root:
+
+   ```bash
+   claude mcp add graph-indexer -- npx -y --prefix / graph-indexer@3.1.0 serve
+   ```
+
+   `--prefix /` makes npx run only the published package, never a copy shipped inside the repository.
+   The version is pinned on purpose: update it by hand when a newer graph-indexer is released.
+
+3. Optional, with the user's consent: `npx -y --prefix / graph-indexer@3.1.0 init --hooks` also writes the
+   Claude Code hooks (an edit check after each edit, grep disambiguation) to `.claude/settings.json`.
+4. Restart Claude Code, or run `/mcp`, and confirm `graph-indexer` is connected.
+
+Then use `find_references`, `call_graph`, `change_impact`, `read_code` and `check_changes`, or delegate
+structural questions to the `code-structure` sub-agent.

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

@@ -0,0 +1,9 @@
+{
+  "name": "graph-indexer",
+  "version": "3.1.0",
+  "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 → claude-code-local}/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "graph-indexer": {
       "command": "npx",
-      "args": ["-y", "graph-indexer@3", "serve"]
+      "args": ["-y", "--prefix", "/", "graph-indexer@3.1.0", "serve"]
     }
   }
 }

package/integrations/claude-code-local/README.md

@@ -0,0 +1,10 @@
+# graph-indexer: full Claude Code plugin (manual install)
+
+This folder is the plugin with everything wired in: the MCP server (`.mcp.json`), the hooks
+(`hooks/`) and the `code-structure` sub-agent. The plugin directory lists only plugins made of
+Markdown and JSON (see `../claude-code`), so this one is not listed there. To use it, copy the
+folder or point a local marketplace at it. `npx -y --prefix / graph-indexer@3.1.0 init --hooks`
+gives the same result without a plugin.
+
+Each release must update the version in `.mcp.json`, `hooks/gi-hook.mjs` and
+`.claude-plugin/plugin.json`; `test/plugin-pins.test.mjs` checks that they equal `package.json`.

package/integrations/claude-code-local/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 → claude-code-local}/hooks/gi-hook.mjs

@@ -20,6 +20,8 @@ import { spawn } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
 
 const PROTOCOL = 1;
+// the exact release this plugin version runs through npx (never a range): keep it equal to package.json's version
+export const VERSION = '3.1.0';
 const WIN = process.platform === 'win32';
 
 export function findRepoRoot(start) {
@@ -43,11 +45,12 @@ export function socketPath(root) {
 
 function trusted(file, root) {
     if (WIN) return true;
-    const dir = path.dirname(file);
-    if (dir === path.join(path.resolve(root), '.graph-indexer')) return fs.existsSync(file);
+    const mine = (st) => !process.getuid || st.uid === process.getuid();
     try {
-        const st = fs.lstatSync(dir);
-        return fs.existsSync(file) && st.isDirectory() && (!process.getuid || st.uid === process.getuid()) && (st.mode & 0o077) === 0;
+        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; }
 }
 
@@ -85,8 +88,11 @@ async function main() {
     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)
-    const child = spawn(WIN ? 'npx.cmd' : 'npx', ['-y', 'graph-indexer@3', 'hook', event], { stdio: ['pipe', 'inherit', 'ignore'], shell: WIN });
+    // 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@${VERSION}`, 'hook', event], { stdio: ['pipe', 'inherit', 'ignore'], shell: WIN });
     child.on('error', () => { /* fail open */ });
     child.stdin.on('error', () => { /* fail open */ });
     child.stdin.end(raw);

package/integrations/opencode/graph-indexer.js

@@ -19,8 +19,9 @@ import { spawn } from 'node:child_process';
 
 const PROTOCOL = 1;
 const WIN = process.platform === 'win32';
-// how to start a resident when none answers (rewritten by `init --local` and installed binaries)
-const DAEMON = ['npx', '-y', 'graph-indexer@3', 'daemon'];
+// how to start a resident when none answers (rewritten by `init --local` and installed binaries);
+// --prefix keeps npx from running a graph-indexer that the repository ships in its own node_modules
+const DAEMON = ['npx', '-y', '--prefix', os.homedir(), 'graph-indexer@3', 'daemon'];
 // OpenCode tool ids → the tool names graph-indexer's hook understands
 const TOOLS = { read: 'Read', grep: 'Grep', bash: 'Bash', edit: 'Edit', write: 'Write' };
 
@@ -46,12 +47,12 @@ function socketPath(root) {
 
 function trusted(file, root) {
     if (WIN) return true;
-    if (!fs.existsSync(file)) return false;
-    const dir = path.dirname(file);
-    if (dir === path.join(path.resolve(root), '.graph-indexer')) return true;
+    const mine = (st) => !process.getuid || st.uid === process.getuid();
     try {
-        const st = fs.lstatSync(dir);
-        return st.isDirectory() && (!process.getuid || st.uid === process.getuid()) && (st.mode & 0o077) === 0;
+        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; }
 }
 
@@ -107,7 +108,11 @@ export const GraphIndexer = async ({ directory, worktree } = {}) => {
                 if (!reply) {
                     if (!started) {
                         started = true;
-                        const child = spawn(DAEMON[0], [...DAEMON.slice(1), '--repo', root], { detached: true, stdio: 'ignore', windowsHide: true, shell: WIN });
+                        // cmd.exe (npx.cmd needs a shell on Windows) would run `&`, `|`… in a path: quote
+                        // every argument, and give up on one that a quote cannot hold
+                        const args = [...DAEMON.slice(1), '--repo', root];
+                        if (WIN && args.some(a => /["%\r\n]/.test(a))) return;
+                        const child = spawn(DAEMON[0], WIN ? args.map(a => `"${a}"`) : args, { detached: true, stdio: 'ignore', windowsHide: true, shell: WIN });
                         child.on('error', () => { /* optional */ });
                         child.unref();
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "graph-indexer",
-    "version": "3.0.0",
+    "version": "3.1.0",
     "description": "Live code graph and search for AI coding agents over MCP: tree-sitter (WASM) symbols, scope/import/type-aware references, call graphs, change impact and hybrid search — local, zero-dependency, no native builds.",
     "type": "module",
     "main": "src/query/intel.mjs",
@@ -34,7 +34,7 @@
         "index": "node bin/graph-indexer.mjs index"
     },
     "engines": {
-        "node": ">=22.5.0"
+        "node": "^22.23.4 || ^24.22.1 || >=26.12.1"
     },
     "repository": {
         "type": "git",

package/src/cli/helper.mjs

@@ -4,7 +4,7 @@
  * index, and replies with the answer alone. The main agent delegates the question and gets back a
  * path:line list instead of the searches and reads behind it, and the lookup runs on a model that
  * costs a fraction per token. `init` writes it for Claude Code (.claude/agents/) and the Claude Code
- * plugin ships the same file (integrations/claude-code/agents/).
+ * plugin ships it too (integrations/claude-code/agents/, with only the frontmatter keys the plugin directory accepts).
  */
 
 export const HELPER_NAME = 'code-structure';
@@ -65,3 +65,17 @@ omitClaudeMd: true
 ${helperInstructions()}
 `;
 }
+
+/**
+ * The same sub-agent for the Claude Code plugin listed in the plugin directory, which accepts only
+ * a short list of frontmatter keys (name and description): the model and the tool limits are left
+ * to the session, and the instructions already say it does not change files.
+ */
+export function pluginAgentFile() {
+    return `---
+name: ${HELPER_NAME}
+description: ${JSON.stringify(DESCRIPTION)}
+---
+${helperInstructions()}
+`;
+}