graph-indexer 3.0.1 → 3.1.1

package/SECURITY.md

@@ -25,32 +25,43 @@ are not maintained; please upgrade to the latest version.
 
 graph-indexer is a local developer tool. Its threat model follows from a few deliberate choices:
 
-- **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 network.** graph-indexer makes no outbound connections: no telemetry, 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. The one exception is explicit and opt-in:
+  `graph-indexer semantic install` downloads the optional embedding model from huggingface.co at a
+  pinned revision and installs it only if every file's SHA-256 matches the digest in the source.
 - **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.
+  (`git rev-parse`, `git ls-files`, `git status`, `git diff`, `git log`, `git show`) run in the
+  indexed repository with fixed arguments, all through one function (`src/util/git.mjs`). 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. The overrides are passed through git's environment (`GIT_CONFIG_COUNT`), which
+  holds any driver name verbatim, including one containing `=`; with a git older than 2.31 that
+  cannot, a repository naming such a driver gets no git call at all. git does not descend into
+  submodules (`--ignore-submodules=all`), whose own config the overrides do not cover. On Windows,
+  `git` and `npx` are looked up on PATH only, never in the repository (the working directory).
 - **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.
+  walk) under the repository root are indexed. Every component of a file's path is resolved, so
+  neither a symbolic link to a file elsewhere on the machine nor a file under a linked directory is
+  read, indexed or served; devices and FIFOs are skipped. Paths given to the tools
+  (`read_code "file.ts:42"`, `outline`, `change_impact`) are resolved the same way and must stay
+  inside the repository; `.git/` and `.graph-indexer/` are never served, in any letter case on a
+  case-insensitive file system. Manifests and other files read outside the index (`package.json`,
+  `tsconfig.json`, `go.mod`, `Cargo.toml`, `svelte.config.*`, `pom.xml`, `build.gradle`, `.gitignore`,
+  Prisma schemas, migrations) are read only as small regular files inside the repository.
+- **Bounded work.** A regular expression given to `search_text` and a glob given to `find_files`
+  run under a 5 s budget, `.gitignore` patterns are matched without backtracking, `search_text`
+  annotates at most 50,000 matching lines, and a file whose syntax makes the structural queries
+  super-linear is given up after 15 s, so none of them can block the server. Tool arguments are held
+  to the bounds their schema declares (depths, limits, list lengths) whatever the client sends.
 - **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
@@ -59,10 +70,14 @@ graph-indexer is a local developer tool. Its threat model follows from a few del
   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.
+  both sides check before using it. On Windows the pipe's name carries a random id that each
+  resident writes to `.graph-indexer/`, so another user of the machine cannot create the pipe first
+  and answer in its place. 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
+  `init`, mode 0700; a `.graph-indexer` that is a symbolic link is refused, symbolic links inside it
+  are removed before anything is written there, and an index committed to the repository is not
+  opened). 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.
 

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,6 +1,6 @@
 {
   "name": "graph-indexer",
-  "version": "3.0.1",
+  "version": "3.1.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",

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.1 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.1 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.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 → claude-code-local}/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "graph-indexer": {
       "command": "npx",
-      "args": ["-y", "--prefix", "/", "graph-indexer@3.0.1", "serve"]
+      "args": ["-y", "--prefix", "/", "graph-indexer@3.1.1", "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.1 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.1';
 const WIN = process.platform === 'win32';
 
 export function findRepoRoot(start) {
@@ -35,7 +37,13 @@ export function findRepoRoot(start) {
 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}`;
+    // a pipe name anyone could compute would let another user of the machine create it first and
+    // answer as the resident: the name carries a random id kept in the private data directory
+    if (WIN) {
+        let id = '';
+        try { id = fs.readFileSync(path.join(abs, '.graph-indexer', 'resident.pipe-id'), 'utf8').trim(); } catch { /* no resident yet */ }
+        return /^[0-9a-f]{32}$/.test(id) ? `\\\\.\\pipe\\graph-indexer-${hash}-${id}` : null;
+    }
     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`);
@@ -55,7 +63,7 @@ function trusted(file, root) {
 /** 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);
+    if (!file || !trusted(file, root)) return Promise.resolve(null);
     return new Promise((resolve) => {
         let done = false, buf = '';
         const sock = net.createConnection(file);
@@ -89,8 +97,11 @@ async function main() {
     // 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 });
+    // It runs from the home directory with the repository passed explicitly: cmd.exe looks for
+    // npx.cmd in the working directory first, which here would be the repository's.
+    if (WIN && /["%\r\n]/.test(root)) return;
+    const q = (a) => (WIN ? `"${a}"` : a);
+    const child = spawn(WIN ? 'npx.cmd' : 'npx', ['-y', '--prefix', q(os.homedir()), `graph-indexer@${VERSION}`, 'hook', event, '--repo', q(root)], { cwd: os.homedir(), 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

@@ -39,7 +39,13 @@ function findRepoRoot(start) {
 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}`;
+    // a pipe name anyone could compute would let another user of the machine create it first and
+    // answer as the resident: the name carries a random id kept in the private data directory
+    if (WIN) {
+        let id = '';
+        try { id = fs.readFileSync(path.join(abs, '.graph-indexer', 'resident.pipe-id'), 'utf8').trim(); } catch { /* no resident yet */ }
+        return /^[0-9a-f]{32}$/.test(id) ? `\\\\.\\pipe\\graph-indexer-${hash}-${id}` : null;
+    }
     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`);
@@ -58,7 +64,7 @@ function trusted(file, root) {
 
 function ask(root, request, totalMs) {
     const file = socketPath(root);
-    if (!trusted(file, root)) return Promise.resolve(null);
+    if (!file || !trusted(file, root)) return Promise.resolve(null);
     return new Promise((resolve) => {
         let done = false, buf = '';
         const sock = net.createConnection(file);
@@ -112,7 +118,8 @@ export const GraphIndexer = async ({ directory, worktree } = {}) => {
                         // 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 });
+                        // from the home directory: cmd.exe would look for npx.cmd in the repository first
+                        const child = spawn(DAEMON[0], WIN ? args.map(a => `"${a}"`) : args, { cwd: os.homedir(), 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.1",
+    "version": "3.1.1",
     "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",

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()}
+`;
+}