@ashkand/code-graph-mcp 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dorkian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,280 @@
+# code-graph-mcp
+
+Local code-intelligence MCP server for mono-repos. It indexes your repo once
+into a knowledge graph — packages, components, frontend routes, HTTP calls,
+backend routes, handlers — and lets any MCP client (Claude Code, Cursor, Codex
+CLI, OpenCode…) query structure directly instead of grepping and re-reading
+files on every question.
+
+Ask "where does `LoginPage` land in the backend?" and get
+`LoginPage → POST /api/auth/login → auth.login` in one tool call, from a graph
+that's already in memory. No file reads, no grep round-trips.
+
+## Why
+
+Agents burn most of their tokens re-discovering structure: listing directories,
+grepping for usages, opening five files to trace one request path. This server
+front-loads that discovery into a single index pass and then answers structural
+questions from memory, with output engineered to be cheap:
+
+- **Compact line-oriented output** — no pretty-printed JSON, no prose padding.
+- **Hard token budgets per response** (default ~2k tokens, tunable per call)
+  with `…+N more (refine query)` truncation instead of overflow.
+- **Path compression** — repo-relative paths, common prefixes stripped in lists.
+- **Incremental re-index** — content-hash manifest; unchanged files are never
+  reparsed.
+- **Savings tracking** — `repo_summary` reports how many tokens of raw file
+  reads the session avoided.
+- **Zero query-time I/O** — every tool answers from in-memory indexes; only
+  `reindex` touches disk.
+
+## What it detects
+
+| Layer | Detected |
+|---|---|
+| Packages | npm workspaces, any `package.json`, `pyproject.toml`, `requirements.txt` |
+| Frontend | React Router routes (`<Route>`, `createBrowserRouter`), exported components, imports, rendered children, custom hooks/stores |
+| HTTP calls | `fetch()`, `axios.<method>()`, `axios({...})`, generic `client.get/post/...()`, template-literal URLs normalized (`` `${API}/users/${id}` `` → `/users/:param`) |
+| Backend | FastAPI (`@app.get`, `APIRouter(prefix=…)`, `include_router(…, prefix=…)` incl. import aliases), Flask (`@app.route`), Express (`app.get`, `router.post`, `app.use('/prefix', router)`) |
+| Cross-layer | frontend call ↔ backend route matching by method + normalized path, `:param`/`{id}`/`${id}` all treated as wildcards |
+
+Parsing is regex/heuristic (deliberately: fast, zero native deps). It won't
+catch every dynamic pattern — that's the tradeoff for indexing thousands of
+files in milliseconds with two pure-JS dependencies.
+
+## Install
+
+### Fastest: let the CLI configure your client
+
+```bash
+# Claude Code — writes .mcp.json AND installs the companion skill
+npx -y @ashkand/code-graph-mcp install claude-code --repo .
+
+# Cursor — writes .cursor/mcp.json
+npx -y @ashkand/code-graph-mcp install cursor --repo .
+
+# anything else — prints ready-to-paste config for Claude Desktop, Codex CLI, …
+npx -y @ashkand/code-graph-mcp install
+```
+
+No npm? Every command also works straight from the repo by swapping
+`@ashkand/code-graph-mcp` for `github:dorkian/code-graph-mcp`.
+
+That's it — restart your client and ask *"where does LoginPage land in the backend?"*
+
+### Or: let your AI install it
+
+Paste this into Claude Code, Cursor, Codex, or any coding agent with shell access, from inside the repo you want indexed:
+
+```text
+Install the code-graph-mcp server in this repo:
+1. Run: npx -y @ashkand/code-graph-mcp install claude-code --repo .
+   (if this isn't Claude Code, run `npx -y @ashkand/code-graph-mcp install`
+   and apply the printed config for the client you are instead)
+2. Add `.codegraph/` to .gitignore if it isn't there.
+3. Run: npx -y @ashkand/code-graph-mcp --repo . --index
+   and show me the node/edge counts it reports.
+4. From now on, prefer the code-graph MCP tools (repo_summary,
+   find_component_relations, map_frontend_to_backend, search_symbols,
+   impact_of_change, visualize_graph) over grep/read_file for questions
+   about repo structure, and call reindex after you edit files.
+```
+
+Step 4 is a summary of the bundled skill — Claude Code users get the full version automatically at `.claude/skills/code-graph/SKILL.md`.
+
+### Manual
+
+```bash
+git clone https://github.com/dorkian/code-graph-mcp.git
+cd code-graph-mcp && npm install
+node bin/code-graph-mcp.js --repo /path/to/your/repo
+```
+
+The graph lives at `<repo>/.codegraph/` — add it to your repo's `.gitignore`.
+Pre-warm the cache (e.g. in CI or a git hook):
+
+```bash
+code-graph-mcp --repo . --index          # incremental
+code-graph-mcp --repo . --index --full   # rebuild from scratch
+```
+
+## Client setup (manual configs)
+
+<details>
+<summary>Claude Code (.mcp.json)</summary>
+
+```json
+{
+  "mcpServers": {
+    "code-graph": {
+      "command": "npx",
+      "args": ["-y", "@ashkand/code-graph-mcp", "--repo", "."]
+    }
+  }
+}
+```
+
+Then copy `skills/code-graph/` into `.claude/skills/` (the `install claude-code` command does both).
+</details>
+
+<details>
+<summary>Cursor (.cursor/mcp.json)</summary>
+
+```json
+{
+  "mcpServers": {
+    "code-graph": {
+      "command": "npx",
+      "args": ["-y", "@ashkand/code-graph-mcp", "--repo", "${workspaceFolder}"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Claude Desktop (claude_desktop_config.json)</summary>
+
+```json
+{
+  "mcpServers": {
+    "code-graph": {
+      "command": "npx",
+      "args": ["-y", "@ashkand/code-graph-mcp", "--repo", "/abs/path/to/repo"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Codex CLI (~/.codex/config.toml)</summary>
+
+```toml
+[mcp_servers.code-graph]
+command = "npx"
+args = ["-y", "@ashkand/code-graph-mcp", "--repo", "/abs/path/to/repo"]
+```
+</details>
+
+Any other MCP client: it's a plain stdio server — run
+`node bin/code-graph-mcp.js --repo <path>` and speak MCP over stdin/stdout.
+
+## Use it as a Claude custom connector (claude.ai / Desktop / mobile)
+
+Claude's custom connectors only accept **remote** MCP servers: Claude connects
+to your server URL from Anthropic's cloud, not from your machine, so a local
+stdio process can't be added directly — the server must be reachable on the
+public internet over Streamable HTTP. That's what `--http` mode is for:
+
+```bash
+# on your VPS, next to a checkout of the repo you want indexed
+npx -y @ashkand/code-graph-mcp --repo /srv/my-monorepo \
+  --http --port 3333 --auth-token "$(openssl rand -hex 24)"
+```
+
+Put it behind your reverse proxy with TLS (Caddy example):
+
+```caddy
+graph.yourdomain.com {
+    reverse_proxy 127.0.0.1:3333
+}
+```
+
+Then in Claude: **Settings → Connectors → Add custom connector** and paste
+
+```
+https://graph.yourdomain.com/mcp/<your-token>
+```
+
+The token-in-URL form exists exactly for this: the connector UI takes a plain
+URL (or OAuth), so the secret rides in the path; API/CLI clients can send
+`Authorization: Bearer <token>` instead. Keep in mind what you're exposing —
+the graph reveals your repo's structure (routes, endpoints, file names), so
+treat the URL like a password, rotate the token if it leaks, and never run
+`--http` without a token on anything internet-facing. Run it as a systemd
+service and add a cron/git-hook `--index` call to keep the graph fresh after
+pushes.
+
+**Who can use your hosted URL — and what they get.** Anyone you share
+`https://graph.yourdomain.com/mcp/<token>` with can add it as a custom
+connector in their own Claude (Settings → Connectors → Add custom connector;
+available on all plans — Free accounts can add one custom connector). But be
+clear about the model: one running instance indexes **one repo on your
+server**, and every connected user queries **that same shared graph**. It is
+not multi-tenant — users can't point your instance at their own codebases.
+Host it to demo the tool or to give a team a shared brain for one codebase;
+for their own repos, users run their own instance (stdio locally via the
+install command, or `--http` on their own box).
+
+## Tools
+
+| Tool | Purpose | Key params |
+|---|---|---|
+| `repo_summary` | Packages, deps, FE/BE routes, counts, session token savings | `detail`, `max_tokens` |
+| `find_component_relations` | Everything related to a component/route: children, parents, hooks, endpoints, imports | `name`, `detail` |
+| `map_frontend_to_backend` | Full chain `Component → HTTP call → backend route → handler`; works from either end | `name` (component, route, or `/path`) |
+| `visualize_graph` | Mermaid/DOT slice: `component-tree` or `fe-to-be` | `name`, `kind`, `format`, `max_nodes` |
+| `search_symbols` | Fuzzy find any node by name/path — replaces grep for "where is X" | `query`, `types`, `limit` |
+| `impact_of_change` | Blast radius: transitive dependents of a node or file | `name`, `depth` |
+| `reindex` | Refresh graph; incremental by default | `full` |
+
+Every tool accepts `max_tokens` (response budget) and, where lists appear,
+`detail: "compact" | "full"`.
+
+Example output (`map_frontend_to_backend`, `name: "LoginPage"`):
+
+```
+LoginPage -> POST /api/auth/login -> POST /api/auth/login (services/api/app/auth.py) -> auth.login
+```
+
+Example diagram (`visualize_graph`, `kind: "fe-to-be"`):
+
+```mermaid
+graph LR
+  n1(("route /login")) --> n2["LoginPage"]
+  n2 -- calls --> n3["POST /api/auth/login"]
+  n3 -- hits --> n4[/"POST /api/auth/login"/]
+  n4 -- handled by --> n5[["fn login"]]
+```
+
+## Storage format
+
+`.codegraph/graph.json` — versioned node/edge lists, loaded into in-memory
+Maps (by id, name, file, endpoint path) at startup; a ~1k-file repo loads in
+well under a second. `.codegraph/manifest.json` — sha1 per indexed file,
+drives incremental re-index and deleted-file pruning. Corrupted or missing
+graph files trigger a clean full re-index, never a crash.
+
+## Development
+
+```bash
+npm install
+npm test   # 57 unit assertions against a bundled fixture mono-repo,
+           # an MCP smoke test speaking real JSON-RPC over stdio,
+           # and an HTTP smoke test covering --http mode + token auth
+```
+
+The fixture under `test/fixture/` is a miniature mono-repo (React app, FastAPI
+service, Express service) exercising every detection path including
+`include_router` alias resolution and template-literal endpoints.
+
+## Publishing this repo to GitHub
+
+Credentials never leave your machine, so push it yourself:
+
+```bash
+cd code-graph-mcp
+git init && git add -A && git commit -m "code-graph-mcp v0.2.0"
+git branch -M main
+git remote add origin https://github.com/dorkian/code-graph-mcp.git
+git push -u origin main
+
+# optional: publish to npm so npx works
+npm login
+npm publish --access public
+```
+
+## License
+
+MIT © dorkian

package/bin/code-graph-mcp.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+// code-graph-mcp CLI
+//   code-graph-mcp --repo <path>                          MCP server (stdio)
+//   code-graph-mcp --repo <path> --http [--port N] [--auth-token T]
+//                                                         MCP server (Streamable HTTP)
+//   code-graph-mcp --repo <path> --index [--full]         index only and exit
+//   code-graph-mcp install claude-code|cursor [--repo p]  configure a client
+import path from "node:path";
+import fs from "node:fs";
+import { fullIndex, incrementalIndex } from "../src/indexer.js";
+import { Graph } from "../src/graph.js";
+import { startServer, startHttpServer } from "../src/server.js";
+import { install } from "../src/install.js";
+
+const args = process.argv.slice(2);
+function flag(name) { return args.includes(name); }
+function opt(name, dflt) {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] ? args[i + 1] : dflt;
+}
+
+if (flag("--help") || flag("-h")) {
+  console.log(`code-graph-mcp — local code-intelligence MCP server
+
+Usage:
+  code-graph-mcp --repo <path>                       start MCP server (stdio)
+  code-graph-mcp --repo <path> --http                start MCP server (Streamable HTTP)
+      [--port 3333] [--host 127.0.0.1] [--auth-token <secret>]
+  code-graph-mcp --repo <path> --index [--full]      build/refresh index and exit
+  code-graph-mcp install claude-code [--repo <path>] write .mcp.json + copy skill
+  code-graph-mcp install cursor      [--repo <path>] write .cursor/mcp.json
+  code-graph-mcp install                             print setup for other clients
+
+The graph is stored at <repo>/.codegraph/ (add it to .gitignore).`);
+  process.exit(0);
+}
+
+const repo = path.resolve(opt("--repo", process.env.CODE_GRAPH_REPO ?? process.cwd()));
+
+if (args[0] === "install") {
+  try { console.log(install(args[1], repo)); process.exit(0); }
+  catch (e) { console.error(`install failed: ${e.message}`); process.exit(1); }
+}
+
+if (!fs.existsSync(repo) || !fs.statSync(repo).isDirectory()) {
+  console.error(`[code-graph-mcp] not a directory: ${repo}`);
+  process.exit(1);
+}
+
+if (flag("--index")) {
+  const existing = flag("--full") ? null : Graph.load(repo);
+  const res = existing ? incrementalIndex(repo, existing) : fullIndex(repo);
+  const s = res.graph.stats();
+  console.log(`indexed (${res.mode}): ${s.nodes} nodes, ${s.edges} edges in ${res.ms}ms; warnings: ${res.warnings.length}`);
+  for (const w of res.warnings.slice(0, 10)) console.log(`  warn: ${w}`);
+  process.exit(0);
+}
+
+if (flag("--http")) {
+  startHttpServer(repo, {
+    port: Number(opt("--port", 3333)),
+    host: opt("--host", "127.0.0.1"),
+    token: opt("--auth-token", null),
+  }).catch((e) => { console.error("[code-graph-mcp] fatal:", e); process.exit(1); });
+} else {
+  startServer(repo).catch((e) => { console.error("[code-graph-mcp] fatal:", e); process.exit(1); });
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@ashkand/code-graph-mcp",
+  "version": "0.2.2",
+  "description": "Local code-intelligence MCP server: index a mono-repo into a knowledge graph (routes, components, API calls, backend handlers) and answer structural questions in a fraction of the tokens.",
+  "type": "module",
+  "bin": {
+    "code-graph-mcp": "bin/code-graph-mcp.js"
+  },
+  "main": "src/server.js",
+  "scripts": {
+    "start": "node bin/code-graph-mcp.js",
+    "test": "node test/run-tests.js && node test/mcp-smoke.js && node test/http-smoke.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "code-intelligence",
+    "knowledge-graph",
+    "claude-code",
+    "cursor",
+    "monorepo",
+    "token-optimization"
+  ],
+  "author": "dorkian",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dorkian/code-graph-mcp.git"
+  },
+  "homepage": "https://github.com/dorkian/code-graph-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/dorkian/code-graph-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.76"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/code-graph/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: code-graph
+description: >-
+  Answer questions about repo structure, architecture, and frontend-to-backend
+  flows by querying the code-graph-mcp tools instead of grepping and reading
+  files. Use this skill whenever the user asks where something is defined, what
+  uses or depends on a component, which backend endpoint or handler a page/route
+  hits, what a repo or package contains, what breaks if a file changes, or wants
+  a diagram of a component tree or FE→BE flow. Also use it BEFORE editing code
+  when adding a feature, to pick the right files with repo_summary and
+  find_component_relations first. Do NOT fall back to read_file/grep for these
+  structural questions while the code-graph MCP server is connected — read files
+  only after the graph has named the exact files worth reading.
+---
+
+# Code Graph
+
+The `code-graph-mcp` server holds a pre-built knowledge graph of this repo:
+packages, files, components, frontend routes, HTTP calls, backend routes, and
+handler functions, with the edges between them. One tool call against the graph
+replaces a grep plus several file reads — use it first, read files second.
+
+## Question → tool mapping
+
+| The user asks… | Call |
+|---|---|
+| "Where does login land in the backend?" / "Which handler serves /users/:id?" | `map_frontend_to_backend` with the component, route, or path |
+| "What uses `Button`?" / "What does `Dashboard` depend on?" | `find_component_relations` |
+| "What's in this repo?" / "Which packages/services exist?" | `repo_summary` |
+| "Where is X defined?" | `search_symbols` (never grep for this) |
+| "What breaks if I change X?" / before a refactor | `impact_of_change` |
+| "Show me the component tree / the flow" | `visualize_graph` |
+| Results look stale after edits | `reindex` (incremental, cheap) |
+
+## Workflow: answering a structural question
+
+1. Call the single most specific tool from the table — not `repo_summary`
+   first "for context" unless the question is actually repo-wide.
+2. Answer from the tool output. Only `read_file` the specific files the graph
+   named, and only if the user needs code-level detail beyond structure.
+3. If a name isn't found, the tool returns closest matches — pick the right
+   one and retry rather than switching to grep.
+
+## Workflow: adding a feature or fixing a bug
+
+1. `repo_summary` — identify the right package/service.
+2. `find_component_relations` on the nearest existing component/route — see
+   its hooks, children, and endpoints so the new code matches local patterns.
+3. `map_frontend_to_backend` if the change crosses the FE/BE boundary — know
+   the handler before touching the client call (and vice versa).
+4. `impact_of_change` on anything you're about to modify — list the blast
+   radius and check the dependents after editing.
+5. Only now read/edit the specific files identified. After substantial edits,
+   call `reindex` so later questions in the session stay accurate.
+
+## Token discipline
+
+- Default `detail: "compact"` is almost always enough; only pass
+  `detail: "full"` when the compact output was truncated on the part you need.
+- Outputs end with `…+N more (refine query…)` when capped — refine (add
+  `types`, a more specific name) rather than immediately raising `max_tokens`.
+- Don't re-call a tool you already called with the same arguments in this
+  conversation; the graph doesn't change unless files change.
+
+## Diagrams
+
+`visualize_graph` returns a ready `graph LR` Mermaid block (or DOT with
+`format: "dot"`). Paste the Mermaid block into the reply inside a
+```mermaid fenced code block so UIs that support it render the diagram; when
+the interface can't render Mermaid, summarize the same slice as an indented
+ASCII tree instead. Use `kind: "fe-to-be"` for request-flow questions and
+`kind: "component-tree"` for UI hierarchy questions.

package/src/graph.js

@@ -0,0 +1,193 @@
+// Graph store for code-graph-mcp.
+// Nodes: { id, type, name, file?, extra? }
+// Edges: { from, to, type }
+// Persisted as JSON (.codegraph/graph.json); indexed in memory for O(1) lookups.
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const NODE_TYPES = [
+  "package", "file", "component", "route", "endpoint-call", "api-route", "handler",
+];
+
+export class Graph {
+  constructor(repoRoot) {
+    this.repoRoot = repoRoot;
+    this.nodes = new Map();          // id -> node
+    this.edges = [];                 // { from, to, type }
+    this.byName = new Map();         // lowercased name -> Set<id>
+    this.byFile = new Map();         // relPath -> Set<id> (nodes defined in file)
+    this.out = new Map();            // id -> [{to,type}]
+    this.in = new Map();             // id -> [{from,type}]
+    this.byEndpointPath = new Map(); // normalized path -> Set<id> (api-route + endpoint-call)
+  }
+
+  // ---------- mutation ----------
+  addNode(node) {
+    this.nodes.set(node.id, node);
+    if (node.name) {
+      const key = node.name.toLowerCase();
+      if (!this.byName.has(key)) this.byName.set(key, new Set());
+      this.byName.get(key).add(node.id);
+    }
+    if (node.file) {
+      if (!this.byFile.has(node.file)) this.byFile.set(node.file, new Set());
+      this.byFile.get(node.file).add(node.id);
+    }
+    if ((node.type === "api-route" || node.type === "endpoint-call") && node.extra?.normPath) {
+      const k = node.extra.normPath;
+      if (!this.byEndpointPath.has(k)) this.byEndpointPath.set(k, new Set());
+      this.byEndpointPath.get(k).add(node.id);
+    }
+    return node;
+  }
+
+  addEdge(from, to, type) {
+    if (!this.nodes.has(from) || !this.nodes.has(to)) return;
+    this.edges.push({ from, to, type });
+    if (!this.out.has(from)) this.out.set(from, []);
+    this.out.get(from).push({ to, type });
+    if (!this.in.has(to)) this.in.set(to, []);
+    this.in.get(to).push({ from, type });
+  }
+
+  // Remove every node defined in `relPath` (and its edges). Used by incremental reindex.
+  removeFile(relPath) {
+    const ids = this.byFile.get(relPath);
+    if (!ids) return 0;
+    const dead = new Set(ids);
+    // file node itself uses id `file:<rel>`
+    dead.add(`file:${relPath}`);
+    for (const id of dead) {
+      const n = this.nodes.get(id);
+      if (!n) continue;
+      this.nodes.delete(id);
+      if (n.name) this.byName.get(n.name.toLowerCase())?.delete(id);
+      if (n.extra?.normPath) this.byEndpointPath.get(n.extra.normPath)?.delete(id);
+    }
+    this.byFile.delete(relPath);
+    const before = this.edges.length;
+    this.edges = this.edges.filter((e) => !dead.has(e.from) && !dead.has(e.to));
+    this.rebuildAdjacency();
+    return before - this.edges.length;
+  }
+
+  rebuildAdjacency() {
+    this.out = new Map();
+    this.in = new Map();
+    for (const e of this.edges) {
+      if (!this.out.has(e.from)) this.out.set(e.from, []);
+      this.out.get(e.from).push({ to: e.to, type: e.type });
+      if (!this.in.has(e.to)) this.in.set(e.to, []);
+      this.in.get(e.to).push({ from: e.from, type: e.type });
+    }
+  }
+
+  // ---------- queries ----------
+  findByName(name) {
+    return [...(this.byName.get(name.toLowerCase()) ?? [])].map((id) => this.nodes.get(id));
+  }
+
+  // Fuzzy: substring + subsequence scoring across node names and file paths.
+  fuzzy(query, limit = 8, types = null) {
+    const q = query.toLowerCase();
+    const scored = [];
+    for (const n of this.nodes.values()) {
+      if (types && !types.includes(n.type)) continue;
+      const hay = `${n.name ?? ""} ${n.file ?? ""}`.toLowerCase();
+      let score = 0;
+      const nameLc = (n.name ?? "").toLowerCase();
+      if (nameLc === q) score = 100;
+      else if (nameLc.startsWith(q)) score = 80;
+      else if (nameLc.includes(q)) score = 60;
+      else if (hay.includes(q)) score = 40;
+      else if (isSubsequence(q, nameLc)) score = 20;
+      if (score > 0) scored.push([score, n]);
+    }
+    scored.sort((a, b) => b[0] - a[0] || (a[1].name ?? "").length - (b[1].name ?? "").length);
+    return scored.slice(0, limit).map(([, n]) => n);
+  }
+
+  neighbors(id, dir = "out", edgeTypes = null) {
+    const list = (dir === "out" ? this.out : this.in).get(id) ?? [];
+    return list
+      .filter((e) => !edgeTypes || edgeTypes.includes(e.type))
+      .map((e) => ({ node: this.nodes.get(dir === "out" ? e.to : e.from), type: e.type }))
+      .filter((e) => e.node);
+  }
+
+  // BFS over reverse edges: who depends (directly or transitively) on `id`.
+  dependents(id, maxDepth = 3, edgeTypes = ["imports", "renders", "calls", "hits-endpoint", "handled-by"]) {
+    const seen = new Map(); // id -> depth
+    let frontier = [id];
+    for (let d = 1; d <= maxDepth && frontier.length; d++) {
+      const next = [];
+      for (const cur of frontier) {
+        for (const { node } of this.neighbors(cur, "in", edgeTypes)) {
+          if (node.id === id || seen.has(node.id)) continue;
+          seen.set(node.id, d);
+          next.push(node.id);
+        }
+      }
+      frontier = next;
+    }
+    return [...seen.entries()].map(([nid, depth]) => ({ node: this.nodes.get(nid), depth }));
+  }
+
+  stats() {
+    const byType = {};
+    for (const n of this.nodes.values()) byType[n.type] = (byType[n.type] ?? 0) + 1;
+    return { nodes: this.nodes.size, edges: this.edges.length, byType };
+  }
+
+  // ---------- persistence ----------
+  static storageDir(repoRoot) { return path.join(repoRoot, ".codegraph"); }
+  static graphPath(repoRoot) { return path.join(Graph.storageDir(repoRoot), "graph.json"); }
+  static manifestPath(repoRoot) { return path.join(Graph.storageDir(repoRoot), "manifest.json"); }
+
+  save() {
+    const dir = Graph.storageDir(this.repoRoot);
+    fs.mkdirSync(dir, { recursive: true });
+    const payload = { version: 1, nodes: [...this.nodes.values()], edges: this.edges };
+    fs.writeFileSync(Graph.graphPath(this.repoRoot), JSON.stringify(payload));
+  }
+
+  /** @returns {Graph|null} null when missing or corrupted (caller falls back to full index — spec E6) */
+  static load(repoRoot) {
+    try {
+      const raw = fs.readFileSync(Graph.graphPath(repoRoot), "utf8");
+      const data = JSON.parse(raw);
+      if (data.version !== 1 || !Array.isArray(data.nodes) || !Array.isArray(data.edges)) return null;
+      const g = new Graph(repoRoot);
+      for (const n of data.nodes) g.addNode(n);
+      for (const e of data.edges) g.addEdge(e.from, e.to, e.type);
+      return g;
+    } catch {
+      return null;
+    }
+  }
+}
+
+function isSubsequence(needle, hay) {
+  let i = 0;
+  for (const c of hay) if (c === needle[i]) i++;
+  return i === needle.length;
+}
+
+// Shorten a list of repo-relative paths by stripping their longest common dir prefix.
+export function shortenPaths(paths) {
+  if (paths.length < 2) return { prefix: "", paths };
+  const split = paths.map((p) => p.split("/"));
+  let common = 0;
+  outer: while (true) {
+    const seg = split[0][common];
+    if (seg === undefined) break;
+    for (const s of split) {
+      if (s.length - 1 <= common || s[common] !== seg) break outer;
+    }
+    common++;
+  }
+  if (common === 0) return { prefix: "", paths };
+  const prefix = split[0].slice(0, common).join("/") + "/";
+  return { prefix, paths: paths.map((p) => p.slice(prefix.length)) };
+}