graph-indexer 3.0.1 → 3.1.0

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.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",

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", "--prefix", "/", "graph-indexer@3.0.1", "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) {
@@ -90,7 +92,7 @@ async function main() {
     // 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 });
+    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/package.json

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

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

package/src/cli/hook.mjs

@@ -29,10 +29,10 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { findRepoRoot, dataDir, DATA_DIR_NAME, readRepoFile } from '../util/paths.mjs';
-import { specForPath } from '../parse/languages.mjs';
+import { codeSpecForPath as specForPath } from '../parse/languages.mjs'; // hooks report on code files only
 
 const MAX_CONTEXT = 1500;
 const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'edit', 'write', 'apply_patch', 'replace', 'write_file']);
@@ -103,15 +103,63 @@ function sessionState(input) {
     };
 }
 
+/**
+ * The commands of a shell line, split at `;`, `&&`, `||` and newlines outside quotes, with heredoc
+ * bodies dropped and `cd DIR` steps left out (agents write `cd repo; sed -n …; grep …`).
+ */
+export function shellSegments(command) {
+    return splitShell(command).filter(x => !/^cd\s+\S+$/.test(x));
+}
+
+function splitShell(command) {
+    const src = String(command ?? '');
+    const out = [];
+    let cur = '', q = null;
+    const lines = src.split('\n');
+    for (let li = 0; li < lines.length; li++) {
+        const line = lines[li];
+        for (let i = 0; i < line.length; i++) {
+            const ch = line[i];
+            if (q) { cur += ch; if (ch === q) q = null; else if (ch === '\\' && q === '"' && i + 1 < line.length) cur += line[++i]; continue; }
+            if (ch === '"' || ch === "'") { q = ch; cur += ch; continue; }
+            if (ch === '\\' && i + 1 < line.length) { cur += ch + line[++i]; continue; }
+            if (ch === ';' || (ch === '&' && line[i + 1] === '&') || (ch === '|' && line[i + 1] === '|')) {
+                out.push(cur); cur = '';
+                if (ch !== ';') i++;
+                continue;
+            }
+            cur += ch;
+        }
+        if (q) { cur += '\n'; continue; } // a quoted string spanning lines
+        // a heredoc (`<<'EOF'`): skip its body up to the delimiter
+        const hd = /<<-?\s*['"]?(\w+)['"]?/.exec(cur);
+        out.push(cur); cur = '';
+        if (hd) while (li + 1 < lines.length && lines[li + 1].trim() !== hd[1]) li++;
+        if (hd) li++;
+    }
+    if (cur) out.push(cur);
+    return out.map(x => x.trim()).filter(Boolean);
+}
+
 /** A file read through the shell: [file, from, to] for `sed -n 'a,bp' f`, `head -n N f`, `cat f`, `nl -ba f | sed -n …`. */
 export function shellRead(command) {
-    const c = String(command ?? '').replace(/^\s*cd\s+\S+\s*&&\s*/, '');
-    let m;
-    if ((m = /^(?:nl\s+-ba\s+|cat\s+-n\s+)(\S+)\s*\|\s*sed\s+-n\s+['"]?(\d+),(\d+)p['"]?\s*$/.exec(c))) return [m[1], +m[2], +m[3]];
-    if ((m = /^sed\s+-n\s+['"]?(\d+),(\d+)p['"]?\s+(\S+)\s*$/.exec(c))) return [m[3], +m[1], +m[2]];
-    if ((m = /^head\s+-(?:n\s*)?(\d+)\s+(\S+)\s*$/.exec(c))) return [m[2], 1, +m[1]];
-    if ((m = /^cat\s+(?:-n\s+)?(\S+\.\w+)\s*$/.exec(c))) return [m[1], 1, 2000];
-    return null;
+    return shellReads(command)[0] ?? null;
+}
+
+/** Every file read in a shell line (`cd repo; sed -n 10,40p a.py; sed -n 5,9p b.py`), relative paths resolved against a `cd` before them. */
+export function shellReads(command) {
+    const out = [];
+    let dir = null;
+    const at = (f) => (dir && !path.isAbsolute(f) ? path.join(dir, f) : f);
+    for (const c of splitShell(command)) {
+        let m;
+        if ((m = /^cd\s+(['"]?)(\S+)\1$/.exec(c))) { dir = path.isAbsolute(m[2]) ? m[2] : path.join(dir ?? '', m[2]); continue; }
+        if ((m = /^(?:nl\s+-ba\s+|cat\s+-n\s+)(\S+)\s*\|\s*sed\s+-n\s+['"]?(\d+),(\d+)p['"]?\s*$/.exec(c))) out.push([at(m[1]), +m[2], +m[3]]);
+        else if ((m = /^sed\s+-n\s+['"]?(\d+),(\d+)p['"]?\s+(\S+)\s*$/.exec(c))) out.push([at(m[3]), +m[1], +m[2]]);
+        else if ((m = /^head\s+-(?:n\s*)?(\d+)\s+(\S+)\s*$/.exec(c))) out.push([at(m[2]), 1, +m[1]]);
+        else if ((m = /^cat\s+(?:-n\s+)?(\S+\.\w+)\s*$/.exec(c))) out.push([at(m[1]), 1, 2000]);
+    }
+    return out;
 }
 
 /** Minimal shell-words split (quotes and escapes) for extracting a grep pattern. */
@@ -158,17 +206,20 @@ function localIndex(root) {
     };
 }
 
-async function afterEdit(root, input, acquire) {
-    const file = input.tool_input?.file_path ?? input.tool_input?.notebook_path ?? input.tool_input?.path ?? null;
-    if (!file) return null;
-    const rel = path.isAbsolute(file) ? path.relative(root, file).split(path.sep).join('/') : file;
-    if (rel.startsWith('..') || !specForPath(rel)) return null;
+async function afterEdit(root, input, acquire, files = null) {
+    if (!files) {
+        const file = input.tool_input?.file_path ?? input.tool_input?.notebook_path ?? input.tool_input?.path ?? null;
+        if (!file) return null;
+        files = [path.isAbsolute(file) ? path.relative(root, file).split(path.sep).join('/') : file];
+    }
+    files = files.filter(rel => !rel.startsWith('..') && specForPath(rel)).slice(0, 6);
+    if (!files.length) return null;
     const ix = await acquire();
     if (!ix) return null;
     const { intel } = ix;
     try {
         const { checkChanges } = await import('../query/check.mjs');
-        const r = await checkChanges(intel, { files: [rel], tests: false });
+        const r = await checkChanges(intel, { files, tests: false });
         if (r.error) return null;
         const lines = [];
         for (const e of r.syntax.slice(0, 3)) lines.push(`${e.path}:${e.line} has a syntax error introduced since the last commit (${e.missing ? `missing ${e.missing}` : 'unexpected code'}): ${e.text.slice(0, 100)}`);
@@ -235,46 +286,68 @@ async function afterGrep(root, input, crawling, acquire) {
  * silent when there is none; and while the agent is crawling, where the names the lines use are defined.
  */
 async function afterRead(root, input, state, crawling, acquire) {
-    let file = null, from = 1, to = 2000;
+    let reads = [];
     if (READ_TOOLS.has(input.tool_name)) {
-        file = input.tool_input?.file_path ?? input.tool_input?.path ?? input.tool_input?.absolute_path ?? null;
+        const file = input.tool_input?.file_path ?? input.tool_input?.path ?? input.tool_input?.absolute_path ?? null;
+        let from = 1, to = 2000;
         const off = Number(input.tool_input?.offset ?? 0), lim = Number(input.tool_input?.limit ?? 0);
         if (off > 0) from = off;
         if (lim > 0) to = from + lim - 1;
-    } else {
-        const r = shellRead(input.tool_input?.command);
-        if (!r) return null;
-        [file, from, to] = r;
-    }
-    if (!file) return null;
+        if (file) reads = [[file, from, to]];
+    } else reads = shellReads(input.tool_input?.command);
     const cwd = input.cwd || root;
-    const abs = path.isAbsolute(file) ? file : path.join(cwd, file);
-    const rel = path.relative(root, abs).split(path.sep).join('/');
-    if (rel.startsWith('..') || !specForPath(rel)) return null;
+    const ranges = reads.map(([file, from, to]) => {
+        const abs = path.isAbsolute(file) ? file : path.join(cwd, file);
+        return { rel: path.relative(root, abs).split(path.sep).join('/'), from, to };
+    }).filter(r => !r.rel.startsWith('..') && specForPath(r.rel)).slice(0, 4);
+    if (!ranges.length) return null;
     const ix = await acquire();
     if (!ix) return null;
     const { intel } = ix;
     try {
-        await intel.revalidate([rel]); // a long-lived index may not have seen the file change yet
-        const out = [];
+        await intel.revalidate([...new Set(ranges.map(r => r.rel))]); // a long-lived index may not have seen the file change yet
+        const facts = [], defs = [];
         const { factsForRange, renderFacts } = await import('../query/facts.mjs');
+        const { definitionsUsed } = await import('../query/read.mjs');
         state.st.facts ??= [];
-        const facts = factsForRange(intel, rel, from, to, { max: 4, shown: new Set(state.st.facts) });
-        if (facts.length) {
-            for (const f of facts) state.st.facts.push(f.key);
-            out.push(`graph-indexer, resolved for these lines:\n${renderFacts(facts).map(l => `  ${l}`).join('\n')}`);
-        }
-        if (crawling) {
-            const { definitionsUsed } = await import('../query/read.mjs');
-            const n = Math.max(1, to - from + 1);
-            const { rows } = definitionsUsed(intel, rel, from, to, { max: Math.min(12, Math.max(4, Math.round(n / 15))), skipIds: new Set(state.st.shown) });
-            for (const r of rows) state.st.shown.push(r.id);
-            if (rows.length) out.push(`graph-indexer: where names used in these lines are defined (read them directly instead of searching):\n${rows.map(r => `  ${r.qname} → ${r.path}:${r.start_line}  ${String(r.sig || r.kind).replace(/\s+/g, ' ').replace(/\s+#.*$/, '').slice(0, 100)}`).join('\n')}`);
+        for (const { rel, from, to } of ranges) {
+            const fs1 = factsForRange(intel, rel, from, to, { max: Math.max(1, 4 - facts.length), shown: new Set(state.st.facts) });
+            for (const f of fs1) { state.st.facts.push(f.key); facts.push(f); }
+            if (crawling) {
+                const n = Math.max(1, to - from + 1);
+                const { rows } = definitionsUsed(intel, rel, from, to, { max: Math.min(12, Math.max(4, Math.round(n / 15))), skipIds: new Set(state.st.shown) });
+                for (const r of rows) { state.st.shown.push(r.id); if (defs.length < 12) defs.push(r); }
+            }
         }
+        const out = [];
+        if (facts.length) out.push(`graph-indexer, resolved for these lines:\n${renderFacts(facts).map(l => `  ${l}`).join('\n')}`);
+        if (defs.length) out.push(`graph-indexer: where names used in these lines are defined (read them directly instead of searching):\n${defs.map(r => `  ${r.qname} → ${r.path}:${r.start_line}  ${String(r.sig || r.kind).replace(/\s+/g, ' ').replace(/\s+#.*$/, '').slice(0, 100)}`).join('\n')}`);
         return out.length ? out.join('\n') : null;
     } finally { ix.release(); }
 }
 
+/**
+ * Source files a shell command changed (`sed -i`, a Python heredoc that rewrites a file, a patch):
+ * the working tree's modified and new files whose modification time moved since the hook last
+ * looked, so the edit checker also follows edits made without the edit tool.
+ */
+function shellEdits(root, state) {
+    let r;
+    try { r = spawnSync('git', ['-C', root, 'status', '--porcelain', '--untracked-files=all', '-z'], { encoding: 'utf8', timeout: 1500 }); } catch { return []; }
+    if (r.status !== 0 || typeof r.stdout !== 'string') return [];
+    const seen = state.st.mtimes ??= {};
+    const changed = [];
+    for (const e of r.stdout.split('\0')) {
+        if (e.length < 4 || e.startsWith('D') || e[1] === 'D') continue;
+        const rel = e.slice(3);
+        if (!specForPath(rel) || rel.startsWith(DATA_DIR_NAME + '/')) continue;
+        let m;
+        try { m = fs.statSync(path.join(root, rel)).mtimeMs; } catch { continue; }
+        if (seen[rel] !== m) { seen[rel] = m; changed.push(rel); }
+    }
+    return changed;
+}
+
 // the lookup rules, for sessions and subagents whose instruction files do not carry them
 const RULES = `How to look code up in this repository (graph-indexer):
 - Several things at once: several tool calls in one message, or one search with alternatives — not one search per turn.
@@ -288,7 +361,7 @@ async function sessionLine(root, { rules = false, acquire }) {
     const { intel } = ix;
     try {
         const st = intel.stats();
-        const line = `graph-indexer has a live index of this repository (${st.files} files, ${st.symbols} symbols). Its MCP tools answer with exact locations: find_references (exact uses, even when other code shares the name), change_impact (what a change affects and which tests to run), check_changes (what an edit broke, and the closest tests), call_graph, read_code (symbols or ranges by name, with where each name they use is defined), search_text, search_code and outline.`;
+        const line = `graph-indexer has a live index of this repository (${st.files} files, ${st.symbols} symbols). Its MCP tools answer with exact locations: explore (the code relevant to a task, its callers, the definitions it uses and its tests, in one call), find_references (exact uses, even when other code shares the name), change_impact (what a change affects and which tests to run), check_changes (what an edit broke, and the closest tests), call_graph, read_code (symbols or ranges by name, with where each name they use is defined), search_text, search_code and outline.`;
         // the managed block of `init` already carries the rules; otherwise add them
         const carried = ['CLAUDE.md', 'AGENTS.md'].some(f => (readRepoFile(root, f) ?? '').includes('<!-- graph-indexer:start -->'));
         return rules || !carried ? `${line}\n${RULES}` : line;
@@ -308,6 +381,7 @@ export async function handleHook(event, input, { root, acquire }) {
         const state = sessionState(input);
         if (EDIT_TOOLS.has(tool)) {
             state.st.nav = 0;
+            shellEdits(root, state); // so a later shell command does not report this edit again
             state.save();
             text = await afterEdit(root, input, acquire);
         } else if (GREP_TOOLS.has(tool) || (SHELL_TOOLS.has(tool) && grepPattern(command))) {
@@ -318,6 +392,12 @@ export async function handleHook(event, input, { root, acquire }) {
             state.st.nav++;
             text = await afterRead(root, input, state, state.st.nav >= CRAWL, acquire);
             state.save();
+        } else if (SHELL_TOOLS.has(tool)) {
+            // any other command may have edited files (`sed -i`, a script): check what it changed
+            const changed = shellEdits(root, state);
+            if (changed.length) state.st.nav = 0;
+            state.save();
+            if (changed.length) text = await afterEdit(root, input, acquire, changed);
         }
     } else if (event === 'session-start' || event === 'subagent-start') {
         name ??= event === 'session-start' ? 'SessionStart' : 'SubagentStart';
@@ -351,7 +431,9 @@ export async function runHook(event, { repo = null, version = null } = {}) {
     const timer = setTimeout(() => process.exit(0), deadlineMs); // fail open: never hold the agent up
     try {
         const input = await readStdin();
-        const root = findRepoRoot(input.cwd || repo || process.cwd());
+        // an explicit --repo wins over the session's directory (a session started elsewhere, with
+        // the repository added to it)
+        const root = findRepoRoot(repo || input.cwd || process.cwd());
         const { askResident, residentRequired } = await import('./resident.mjs');
         const reply = await askResident(root, { op: 'hook', event, input }, { version, totalMs: 2000 });
         let out = null;

package/src/cli/init.mjs

@@ -26,6 +26,8 @@ const SNIPPET = `${BLOCK_START}
 - Check once: run the tests that cover your change when you are done; do not re-run a check nothing has changed.
 
 The \`graph-indexer\` MCP server answers what a text search cannot answer exactly:
+- Fixing an issue or bug report: make your first call \`explore\` with the names and terms the issue uses (or its text as written). It ranks the code where the names the issue uses meet (usually what you will change) and shows it with its callers, the definitions it uses and the tests to run; read further only what it leaves out.
+- Starting on any other task in code you have not read: \`explore\` with the task in words.
 - Uses of a function, method or class that other code shares a name with: \`find_references\` (exact call sites, says when the list is complete; kind \`inherit\` for subclasses and implementations). Callers of callers: \`call_graph\`.
 - Before changing a signature other code relies on: \`change_impact\`; after: \`check_changes\`.
 ${BLOCK_END}`;
@@ -209,6 +211,7 @@ export async function runInit({ opt, flag, repo: repoArg = null }) {
     const hooks = flag('--hooks');
     const noInstructions = flag('--no-instructions');
     const noHelper = flag('--no-helper');
+    const noDemo = flag('--no-demo');
     const all = flag('--all');
     const agentList = opt('--agents');
     let chosen;
@@ -267,6 +270,18 @@ export async function runInit({ opt, flag, repo: repoArg = null }) {
     }
     process.stdout.write(`graph-indexer init ${dryRun ? '(dry run) ' : ''}in ${repo}\n  ${report.join('\n  ')}\n\n` +
         `Other agents (Claude Desktop, JetBrains AI Assistant, Cline): add an MCP server with command "npx" and args ${JSON.stringify([...NPX_ARGS, 'serve', '--repo', repo])}.\n` +
-        `Build the index now with: npx ${NPX_ARGS.join(' ')} index   (the server also builds it on first start)\n` +
+        (dryRun || noDemo ? `Build the index now with: npx ${NPX_ARGS.join(' ')} index   (the server also builds it on first start)\n` : '') +
         (hooks ? '' : `Optional: graph-indexer init --hooks adds Claude Code hooks (edit check after each edit, grep disambiguation).\n`));
+    if (dryRun || noDemo) return;
+    // build the index now (the server would on first start) and show what it answers here
+    const { CodeIntel } = await import('../query/intel.mjs');
+    const { showcaseText } = await import('../query/showcase.mjs');
+    const intel = new CodeIntel({ root: repo });
+    try {
+        let last = 0;
+        await intel.open({ onProgress: (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'); } } });
+        process.stdout.write(`\n${await showcaseText(intel)}\n`);
+    } catch (e) {
+        process.stdout.write(`\nThe index could not be built now (${e.message}); the server builds it on first start.\n`);
+    } finally { intel.close(); }
 }

package/src/cli/resident.mjs

@@ -16,7 +16,7 @@
  *   { v, version, op: 'hook', event, input }     → { ok, out }   out: what the hook prints, or null
  *   { v, version, op: 'tool', calls }            → { ok, out }   out: the CLI's output text
  * A request from another graph-indexer version gets { ok: false } and the client falls back, except
- * from thin clients that only relay hooks (`any: true`, integrations/claude-code/hooks/gi-hook.mjs).
+ * from thin clients that only relay hooks (`any: true`, integrations/claude-code-local/hooks/gi-hook.mjs).
  *
  * The socket is only reachable by its owner: inside the repository's .graph-indexer/ directory,
  * or, when that path is too long for a Unix socket, in a per-user directory with mode 0700 that