@colbymchenry/codegraph 0.9.8 → 0.9.9

package/README.md

@@ -4,7 +4,7 @@
 
 ### Supercharge Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity, and Kiro with Semantic Code Intelligence
 
-**~25% cheaper · ~62% fewer tool calls · 100% local**
+**~16% cheaper · ~58% fewer tool calls · 100% local**
 
 ### [Documentation & Website →](https://colbymchenry.github.io/codegraph/)
 
@@ -83,21 +83,21 @@ When Claude Code explores a codebase, it spawns **Explore agents** that scan fil
 
 ### Benchmark Results
 
-Tested across **7 real-world open-source codebases** spanning 7 languages, comparing an agent (Claude Code, headless) answering one architecture question **with** and **without** CodeGraph. Each cell is the savings at the **median of 4 runs per arm**. _Re-validated on Opus 4.8 (2026-05-29), on the build with per-symbol adaptive `codegraph_explore` sizing._
+Tested across **7 real-world open-source codebases** spanning 7 languages, comparing an agent (Claude Code, headless) answering one architecture question **with** and **without** CodeGraph. Each cell is the savings at the **median of 4 runs per arm**. _Re-validated on Opus 4.8 (2026-06-02), on the current build (`codegraph_explore` as the primary tool)._
 
-> **Average: 25% cheaper · 57% fewer tokens · 23% faster · 62% fewer tool calls**
+> **Average: 16% cheaper · 47% fewer tokens · 22% faster · 58% fewer tool calls**
 
 | Codebase | Language | Cost | Tokens | Time | Tool calls |
 |----------|----------|------|--------|------|------------|
-| **VS Code** | TypeScript · ~10k files | 33% cheaper | 70% fewer | 27% faster | 80% fewer |
-| **Excalidraw** | TypeScript · ~640 | 27% cheaper | 61% fewer | 26% faster | 70% fewer |
-| **Django** | Python · ~3k | 23% cheaper | 70% fewer | 28% faster | 77% fewer |
-| **Tokio** | Rust · ~790 | 35% cheaper | 70% fewer | 37% faster | 79% fewer |
-| **OkHttp** | Java · ~645 | 11% cheaper | 48% fewer | 26% faster | 70% fewer |
-| **Gin** | Go · ~110 | 15% cheaper | 35% fewer | 9% faster | 47% fewer |
-| **Alamofire** | Swift · ~110 | 28% cheaper | 46% fewer | 7% faster | 13% fewer |
+| **VS Code** | TypeScript · ~10k files | 18% cheaper | 64% fewer | 11% faster | 81% fewer |
+| **Excalidraw** | TypeScript · ~640 | even | 25% fewer | 27% faster | 40% fewer |
+| **Django** | Python · ~3k | 8% cheaper | 60% fewer | 13% faster | 77% fewer |
+| **Tokio** | Rust · ~790 | even | 38% fewer | 18% faster | 57% fewer |
+| **OkHttp** | Java · ~645 | 25% cheaper | 54% fewer | 31% faster | 50% fewer |
+| **Gin** | Go · ~110 | 19% cheaper | 23% fewer | 24% faster | 44% fewer |
+| **Alamofire** | Swift · ~110 | 40% cheaper | 64% fewer | 33% faster | 58% fewer |
 
-CodeGraph cuts **cost, tokens, tool calls, and time on every repo** — across small, medium, and large codebases — and answers most of them with **zero file reads**, while the no-CodeGraph agent spends its budget on grep/find/Read discovery. `codegraph_explore` shows the answer in full — the mechanism plus the exact methods you asked about, even when they're buried in a multi-thousand-line file — while collapsing redundant interchangeable implementations to signatures, so the response is sized to the *answer* rather than the file count. The cost margin is narrowest on the smallest repos, where a modern model's native search is already cheap, but it stays solidly positive across the board.
+CodeGraph cuts **tokens, tool calls, and wall-clock time on every repo** — across small, medium, and large codebases — and answers them with **near-zero file reads**, while the no-CodeGraph agent spends its budget on grep/find/Read discovery. `codegraph_explore` shows the answer in full — the mechanism plus the exact methods you asked about, even when they're buried in a multi-thousand-line file — while collapsing redundant interchangeable implementations to signatures, so the response is sized to the *answer* rather than the file count. **Cost stays flat-to-cheaper everywhere** — largest on the small repos (Alamofire, OkHttp), roughly break-even on the most response-heavy ones (Excalidraw, Tokio), where CodeGraph trades the no-CodeGraph agent's many small grep/read round-trips for a few large, cache-heavy tool responses.
 
 <details>
 <summary><strong>Per-repo breakdown — WITH vs WITHOUT (median of 4)</strong></summary>
@@ -105,79 +105,79 @@ CodeGraph cuts **cost, tokens, tool calls, and time on every repo** — across s
 **VS Code** · ~10k files
 | Metric | WITH cg | WITHOUT cg | Δ |
 |---|---|---|---|
-| Time | 1m 37s | 2m 13s | 27% faster |
+| Time | 1m 59s | 2m 13s | 11% faster |
 | File Reads | 0 | 9 | −9 |
 | Grep/Bash | 0 | 11 | −11 |
-| Tool calls | 4 | 21 | 80% fewer |
-| Total tokens | 545k | 1.79M | 70% fewer |
-| Cost | $0.55 | $0.83 | 33% cheaper |
+| Tool calls | 4 | 21 | 81% fewer |
+| Total tokens | 640k | 1.79M | 64% fewer |
+| Cost | $0.68 | $0.83 | 18% cheaper |
 
 **Excalidraw** · ~640 files
 | Metric | WITH cg | WITHOUT cg | Δ |
 |---|---|---|---|
-| Time | 1m 34s | 2m 6s | 26% faster |
+| Time | 1m 32s | 2m 6s | 27% faster |
 | File Reads | 0 | 7 | −7 |
-| Grep/Bash | 0 | 8 | −8 |
-| Tool calls | 5 | 15 | 70% fewer |
-| Total tokens | 651k | 1.69M | 61% fewer |
-| Cost | $0.57 | $0.78 | 27% cheaper |
+| Grep/Bash | 1 | 8 | −7 |
+| Tool calls | 9 | 15 | 40% fewer |
+| Total tokens | 1.27M | 1.69M | 25% fewer |
+| Cost | $0.78 | $0.78 | even |
 
 **Django** · ~3k files
 | Metric | WITH cg | WITHOUT cg | Δ |
 |---|---|---|---|
-| Time | 1m 25s | 1m 58s | 28% faster |
+| Time | 1m 43s | 1m 58s | 13% faster |
 | File Reads | 0 | 9 | −9 |
 | Grep/Bash | 0 | 5 | −5 |
 | Tool calls | 3 | 13 | 77% fewer |
-| Total tokens | 419k | 1.41M | 70% fewer |
-| Cost | $0.48 | $0.62 | 23% cheaper |
+| Total tokens | 559k | 1.41M | 60% fewer |
+| Cost | $0.57 | $0.62 | 8% cheaper |
 
 **Tokio** · ~790 files
 | Metric | WITH cg | WITHOUT cg | Δ |
 |---|---|---|---|
-| Time | 1m 28s | 2m 20s | 37% faster |
+| Time | 1m 55s | 2m 20s | 18% faster |
 | File Reads | 0 | 8 | −8 |
 | Grep/Bash | 0 | 6 | −6 |
-| Tool calls | 3 | 14 | 79% fewer |
-| Total tokens | 522k | 1.73M | 70% fewer |
-| Cost | $0.53 | $0.82 | 35% cheaper |
+| Tool calls | 6 | 14 | 57% fewer |
+| Total tokens | 1.08M | 1.73M | 38% fewer |
+| Cost | $0.82 | $0.82 | even |
 
 **OkHttp** · ~645 files
 | Metric | WITH cg | WITHOUT cg | Δ |
 |---|---|---|---|
-| Time | 1m 6s | 1m 29s | 26% faster |
-| File Reads | 1 | 4 | −3 |
-| Grep/Bash | 0 | 6 | −6 |
-| Tool calls | 3 | 10 | 70% fewer |
-| Total tokens | 572k | 1.10M | 48% fewer |
-| Cost | $0.48 | $0.55 | 11% cheaper |
+| Time | 1m 1s | 1m 29s | 31% faster |
+| File Reads | 0 | 4 | −4 |
+| Grep/Bash | 2 | 6 | −4 |
+| Tool calls | 5 | 10 | 50% fewer |
+| Total tokens | 502k | 1.10M | 54% fewer |
+| Cost | $0.41 | $0.55 | 25% cheaper |
 
 **Gin** · ~110 files
 | Metric | WITH cg | WITHOUT cg | Δ |
 |---|---|---|---|
-| Time | 1m 28s | 1m 37s | 9% faster |
-| File Reads | 0 | 6 | −6 |
-| Grep/Bash | 0 | 2 | −2 |
-| Tool calls | 5 | 9 | 47% fewer |
-| Total tokens | 552k | 847k | 35% fewer |
-| Cost | $0.48 | $0.57 | 15% cheaper |
+| Time | 1m 14s | 1m 37s | 24% faster |
+| File Reads | 1 | 6 | −5 |
+| Grep/Bash | 1 | 2 | −1 |
+| Tool calls | 5 | 9 | 44% fewer |
+| Total tokens | 651k | 847k | 23% fewer |
+| Cost | $0.46 | $0.57 | 19% cheaper |
 
 **Alamofire** · ~110 files
 | Metric | WITH cg | WITHOUT cg | Δ |
 |---|---|---|---|
-| Time | 2m 11s | 2m 21s | 7% faster |
-| File Reads | 3 | 9 | −6 |
-| Grep/Bash | 2 | 4 | −2 |
-| Tool calls | 11 | 12 | 13% fewer |
-| Total tokens | 1.13M | 2.10M | 46% fewer |
-| Cost | $0.69 | $0.95 | 28% cheaper |
+| Time | 1m 35s | 2m 21s | 33% faster |
+| File Reads | 0 | 9 | −9 |
+| Grep/Bash | 0 | 4 | −4 |
+| Tool calls | 5 | 12 | 58% fewer |
+| Total tokens | 766k | 2.10M | 64% fewer |
+| Cost | $0.57 | $0.95 | 40% cheaper |
 
 </details>
 
 <details>
 <summary><strong>Full benchmark details</strong></summary>
 
-**Methodology.** Each arm is `claude -p` (Claude Opus 4.8) run headlessly against the repo with `--strict-mcp-config`: **WITH** = CodeGraph's MCP server enabled, **WITHOUT** = an empty MCP config. Built-in Read/Grep/Bash stay available to both. Same question per repo, **4 runs per arm, median reported**. Cost = the run's `total_cost_usd`; Tokens = total tokens processed (input incl. cached + output); Time = wall-clock; Tool calls = every tool invocation, including those inside any sub-agents the model spawns. Repos cloned at `--depth 1` and indexed by the same CodeGraph build that served them. Re-validated 2026-05-29 on the build with per-symbol adaptive `codegraph_explore` sizing. These numbers are lower than the prior Opus 4.7 validation — not a CodeGraph regression but a stronger native baseline: Opus 4.8 greps/reads efficiently on the main thread instead of fanning out into large Explore-subagent sweeps, so the no-CodeGraph arm is leaner than it used to be. Per-repo numbers move run-to-run with how hard the without-arm thrashes (the median-of-4 smooths it, but tails remain — e.g. Django's without-arm hit $2.71/14m one batch).
+**Methodology.** Each arm is `claude -p` (Claude Opus 4.8) run headlessly against the repo with `--strict-mcp-config`: **WITH** = CodeGraph's MCP server enabled, **WITHOUT** = an empty MCP config. Built-in Read/Grep/Bash stay available to both. Same question per repo, **4 runs per arm, median reported**. Cost = the run's `total_cost_usd`; Tokens = total tokens processed (input incl. cached + output); Time = wall-clock; Tool calls = every tool invocation, including those inside any sub-agents the model spawns. Repos cloned at `--depth 1` and indexed by the same CodeGraph build that served them. Re-validated 2026-06-02 on the current build. These numbers are lower than the prior Opus 4.7 validation — not a CodeGraph regression but a stronger native baseline: Opus 4.8 greps/reads efficiently on the main thread instead of fanning out into large Explore-subagent sweeps, so the no-CodeGraph arm is leaner than it used to be. Per-repo numbers move run-to-run with how hard the without-arm thrashes (the median-of-4 smooths it, but tails remain — e.g. Django's without-arm hit $2.71/14m one batch).
 
 **Queries:**
 | Codebase | Query |
@@ -190,7 +190,7 @@ CodeGraph cuts **cost, tokens, tool calls, and time on every repo** — across s
 | Gin | "How does gin route requests through its middleware chain?" |
 | Alamofire | "How does Alamofire build, send, and validate a request?" |
 
-**Why CodeGraph wins:** with the index available, the agent answers directly — `codegraph_context` to map the area, then one `codegraph_explore` for the relevant source — and stops, usually with zero file reads. Without it, the agent spends most of its budget on discovery (find/ls/grep) before reading the right code. CodeGraph only helps when queried *directly*, so its instructions steer agents to answer directly rather than delegate exploration to file-reading sub-agents — otherwise a sub-agent reads files regardless and CodeGraph becomes overhead.
+**Why CodeGraph wins:** with the index available, the agent answers directly — usually one `codegraph_explore` returns the relevant source — and stops, usually with zero file reads. Without it, the agent spends most of its budget on discovery (find/ls/grep) before reading the right code. CodeGraph only helps when queried *directly*, so its instructions steer agents to answer directly rather than delegate exploration to file-reading sub-agents — otherwise a sub-agent reads files regardless and CodeGraph becomes overhead.
 
 </details>
 
@@ -365,7 +365,7 @@ npm install -g @colbymchenry/codegraph
   "permissions": {
     "allow": [
       "mcp__codegraph__codegraph_search",
-      "mcp__codegraph__codegraph_context",
+      "mcp__codegraph__codegraph_explore",
       "mcp__codegraph__codegraph_callers",
       "mcp__codegraph__codegraph_callees",
       "mcp__codegraph__codegraph_impact",
@@ -385,7 +385,7 @@ npm install -g @colbymchenry/codegraph
 CodeGraph's MCP server delivers its usage guidance to your agent **automatically**, in the MCP `initialize` response — there's no instructions file to manage and nothing is added to your `CLAUDE.md` / `AGENTS.md` / `GEMINI.md`. In short, it tells the agent to:
 
 - **Answer structural questions directly with CodeGraph** — it *is* the pre-built index, so a grep/read loop just repeats work it already did. Treat the returned source as already read.
-- **Pick the tool by intent:** `codegraph_context` to map an area, `codegraph_trace` for "how does X reach Y", `codegraph_explore` to survey several symbols, `codegraph_search` to find a symbol, `codegraph_callers`/`codegraph_callees` to walk call flow, `codegraph_impact` before editing, `codegraph_node` for one symbol's source.
+- **Pick the tool by intent:** `codegraph_explore` for almost anything — "how does X work", a flow/"how does X reach Y", or surveying an area (one call returns the relevant symbols' source grouped by file); `codegraph_search` to just locate a symbol; `codegraph_callers`/`codegraph_callees` to walk call flow; `codegraph_impact` before editing; `codegraph_node` for one specific symbol's full source (it returns every overload for an ambiguous name).
 - **Trust the results — don't re-verify with grep**, and check the staleness banner after edits.
 - If `.codegraph/` doesn't exist yet, offer to run `codegraph init -i`.
 
@@ -410,7 +410,7 @@ The exact text is `src/mcp/server-instructions.ts` — the single source of trut
 ┌───────────────────────────────────────────────────────────────────┐
 │                        CodeGraph MCP Server                       │
 │                                                                   │
-│       context · trace · explore · callers · callees · impact      │
+│       explore · search · callers · callees · impact · node        │
 │                                 │                                 │
 │                                 ▼                                 │
 │                       SQLite knowledge graph                      │
@@ -441,7 +441,6 @@ codegraph sync [path]             # Incremental update
 codegraph status [path]           # Show statistics
 codegraph query <search>          # Search symbols (--kind, --limit, --json)
 codegraph files [path]            # Show file structure (--format, --filter, --max-depth, --json)
-codegraph context <task>          # Build context for AI (--format, --max-nodes)
 codegraph callers <symbol>        # Find what calls a function/method (--limit, --json)
 codegraph callees <symbol>        # Find what a function/method calls (--limit, --json)
 codegraph impact <symbol>         # Analyze what code is affected by changing a symbol (--depth, --json)
@@ -485,14 +484,12 @@ When running as an MCP server, CodeGraph exposes these tools to Claude Code:
 
 | Tool | Purpose |
 |------|---------|
+| `codegraph_explore` | **Primary.** Answer almost any question in one call — "how does X work", a flow ("how does X reach Y"), or surveying an area — returning the relevant symbols' verbatim source grouped by file, plus a relationship map and blast radius. Surfaces dynamic-dispatch hops (callbacks, React re-render, interface→impl) grep can't follow. |
 | `codegraph_search` | Find symbols by name across the codebase |
-| `codegraph_context` | Build relevant code context for a task |
-| `codegraph_trace` | Trace the call path between two symbols ("how does X reach Y") in one call — each hop with its body inline, following dynamic-dispatch hops (callbacks, React re-render, interface→impl) that grep can't |
 | `codegraph_callers` | Find what calls a function |
 | `codegraph_callees` | Find what a function calls |
 | `codegraph_impact` | Analyze what code is affected by changing a symbol |
-| `codegraph_node` | Get details about a specific symbol (optionally with source code) |
-| `codegraph_explore` | Return source for several related symbols grouped by file, plus a relationship map, in one call |
+| `codegraph_node` | Get one specific symbol's details + full source (returns every overload for an ambiguous name) |
 | `codegraph_files` | Get indexed file structure (faster than filesystem scanning) |
 | `codegraph_status` | Check index health and statistics |
 

package/dist/context/index.d.ts

@@ -7,6 +7,7 @@
 import { Subgraph, TaskContext, TaskInput, BuildContextOptions, FindRelevantContextOptions } from '../types';
 import { QueryBuilder } from '../db/queries';
 import { GraphTraverser } from '../graph';
+export { LOW_CONFIDENCE_MARKER } from './markers';
 /**
  * Context Builder
  *
@@ -33,6 +34,14 @@ export declare class ContextBuilder {
      * @returns TaskContext (structured) or formatted string
      */
     buildContext(input: TaskInput, options?: BuildContextOptions): Promise<TaskContext | string>;
+    /**
+     * Honest handoff appended when retrieval confidence is low (the query matched
+     * mostly common words). Instead of the usual "this covers the surface" framing
+     * — which, when wrong, sends the agent off to Read/Grep — it admits the
+     * uncertainty and routes the agent to the precise tools (explore with real
+     * symbol names, search, or files to browse the closest areas we *did* surface).
+     */
+    private buildLowConfidenceNote;
     /**
      * Surface short call-paths among the symbols this context already found,
      * derived in-memory from the subgraph's `calls` edges (no extra queries).

package/dist/context/markers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Stable sentinel strings shared between the context builder (which emits them
+ * into its markdown) and the MCP layer (which detects them to adjust framing).
+ *
+ * Intentionally a dependency-free leaf module: the MCP tool layer imports this
+ * to recognise a low-confidence response, and routing that recognition through
+ * the full context module would drag its dependencies onto the cold-start path.
+ * Keep this file import-free.
+ */
+/**
+ * Heading that leads the honest low-confidence handoff appended to a context
+ * response when the query resolved only to weak/isolated matches. The MCP layer
+ * checks for it to suppress the contradictory "this is comprehensive, don't call
+ * explore" small-repo footer. Changing the text is a breaking sentinel change —
+ * both the emitter (`ContextBuilder`) and the detector (`src/mcp/tools.ts`)
+ * import this constant, so they stay in sync automatically.
+ */
+export declare const LOW_CONFIDENCE_MARKER = "### \u26A0\uFE0F Low-confidence match";
+//# sourceMappingURL=markers.d.ts.map

package/dist/extraction/tree-sitter.d.ts

@@ -97,6 +97,32 @@ export declare class TreeSitterExtractor {
      * Extracts each declarator as a 'field' kind node inside the owning class.
      */
     private extractField;
+    /**
+     * Extract function-valued properties of an object literal as named function
+     * nodes (named by their property key). Shared by the two object-of-functions
+     * shapes in extractVariable: the object as a direct const value, and the
+     * object returned by a store-initializer call. Handles both `key: () => {}` /
+     * `key: function() {}` pairs and method shorthand `key() {}`.
+     */
+    private extractObjectLiteralFunctions;
+    /** Property-key text with surrounding quotes stripped (`'foo'` → `foo`). */
+    private objectKeyName;
+    /**
+     * Given a `call_expression` initializer (`create((set, get) => ({...}))`),
+     * find the object literal RETURNED by a function argument — descending through
+     * nested call_expression arguments so middleware wrappers are unwrapped
+     * (`create(persist((set, get) => ({...}), {...}))`, devtools, immer,
+     * subscribeWithSelector). Returns null when no such object is found — the
+     * common case for ordinary call initializers — so this stays cheap and silent
+     * rather than guessing. Keyed purely on AST shape; no library names.
+     */
+    private findInitializerReturnedObject;
+    /**
+     * The object literal a function expression returns — either the `=> ({...})`
+     * arrow form (a parenthesized_expression wrapping an object) or a
+     * `=> { return {...} }` block. Returns null for any other body shape.
+     */
+    private functionReturnedObject;
     /**
      * Extract a variable declaration (const, let, var, etc.)
      *

package/dist/index.d.ts

@@ -227,6 +227,12 @@ export declare class CodeGraph {
      * Get all nodes of a specific kind
      */
     getNodesByKind(kind: Node['kind']): Node[];
+    /**
+     * Get ALL nodes with an exact name (direct index lookup, not FTS-ranked/capped).
+     * Used to enumerate every overload of a heavily-overloaded name so the specific
+     * definition the caller wants is never dropped below a search cut.
+     */
+    getNodesByName(name: string): Node[];
     /**
      * Search nodes by text
      */
@@ -235,7 +241,7 @@ export declare class CodeGraph {
      * Find the project's "primary route file" — the file with the densest
      * concentration of framework-emitted `route` nodes (≥3 routes, ≥30%
      * of all non-test routes). Used to inline the routing config in
-     * `codegraph_context` responses on small realworld template repos
+     * `codegraph_explore` responses on small realworld template repos
      * (rails-realworld, laravel-realworld, drupal-admintoolbar, …) where
      * Glob+Read of `routes.rb`/`urls.py`/etc. otherwise beats codegraph.
      */

package/dist/mcp/server-instructions.d.ts

@@ -15,5 +15,5 @@
  * burn tokens. Reference only tools that exist on `main`; gate any
  * conditional tools behind feature checks if/when they ship.
  */
-export declare const SERVER_INSTRUCTIONS = "# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\nCodegraph is a SQLite knowledge graph of every symbol, edge, and file\nin the workspace. Reads are sub-millisecond; the index lags writes by\nabout a second through the file watcher. Consult it BEFORE writing or\nediting code, not during.\n\n## Answer directly \u2014 don't delegate exploration\n\nFor \"how does X work\", architecture, trace, or where-is-X questions,\nanswer DIRECTLY using 2-3 codegraph calls: `codegraph_context` first,\nthen ONE `codegraph_explore` for the source of the symbols it surfaces.\nCodegraph IS the pre-built search index \u2014 so delegating the lookup to a\nseparate file-reading sub-task/agent, or running your own grep + read\nloop, repeats work codegraph already did and costs more for the same\nanswer. Reach for raw Read/Grep only to confirm a specific detail\ncodegraph didn't cover. A direct codegraph answer is typically a handful\nof calls; a grep/read exploration is dozens.\n\n## Tool selection by intent\n\n- **\"What is the symbol named X?\"** \u2192 `codegraph_search`\n- **\"What's the deal with this task / feature / area?\"** \u2192 `codegraph_context` (PRIMARY \u2014 composes search + node + callers + callees in one call)\n- **\"How does X reach/become Y? / trace the flow / the path from X to Y\"** \u2192 `codegraph_trace` (ONE call returns the whole call path, including dynamic-dispatch hops \u2014 callbacks, React re-render, JSX children \u2014 that grep can't follow)\n- **\"What calls this?\"** \u2192 `codegraph_callers`\n- **\"What does this call?\"** \u2192 `codegraph_callees`\n- **\"What would changing this break?\"** \u2192 `codegraph_impact`\n- **\"Show me this symbol's source / signature / docstring.\"** \u2192 `codegraph_node`\n- **\"Show me several related symbols' source / survey an area.\"** \u2192 `codegraph_explore` (ONE capped call; prefer over many codegraph_node/Read)\n- **\"What's in directory X?\"** \u2192 `codegraph_files`\n- **\"Is the index ready / what's its size?\"** \u2192 `codegraph_status`\n\n## Common chains\n\n- **Flow / \"how does X reach Y\"**: `codegraph_trace` from\u2192to FIRST \u2014 one call returns the entire path with dynamic-dispatch hops bridged. Then ONE `codegraph_explore` for the hop bodies if you need them. Do NOT reconstruct the path with `codegraph_search` + `codegraph_callers` \u2014 that's exactly what trace does in a single call.\n- **Onboarding**: `codegraph_context` first. If still unclear, `codegraph_explore` for breadth, then `codegraph_node` on specific symbols.\n- **Refactor planning**: `codegraph_search` \u2192 `codegraph_callers` \u2192 `codegraph_impact`. The blast-radius answer comes from impact, not from walking callers manually.\n- **Debugging a regression**: `codegraph_callers` of the suspected symbol; widen with `codegraph_impact` if an unexpected call appears.\n\n## Anti-patterns\n\n- **Trust codegraph's results \u2014 don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.\n- **Don't grep first** when looking up a symbol by name \u2014 `codegraph_search` is faster and returns kind + location + signature.\n- **Don't chain `codegraph_search` + `codegraph_node`** when you just want context \u2014 `codegraph_context` is one round-trip.\n- **Don't loop `codegraph_node` over many symbols** \u2014 one `codegraph_explore` call returns them all grouped by file, while each separate call re-reads the whole context and costs far more. Use `codegraph_node` for a single symbol.\n- **After editing, check the staleness banner.** When a tool response starts with \"\u26A0\uFE0F Some files referenced below were edited since the last index sync\u2026\", the listed files are pending re-index \u2014 Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust codegraph. `codegraph_status` also lists pending files under \"Pending sync\".\n\n## Limitations\n\n- If a tool reports the project isn't initialized, `.codegraph/` doesn't exist yet \u2014 offer to run `codegraph init -i` to build the index.\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.\n";
+export declare const SERVER_INSTRUCTIONS = "# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\nCodegraph is a SQLite knowledge graph of every symbol, edge, and file\nin the workspace. Reads are sub-millisecond; the index lags writes by\nabout a second through the file watcher. Consult it BEFORE writing or\nediting code, not during.\n\n## Answer directly \u2014 don't delegate exploration\n\nFor \"how does X work\", architecture, trace, or where-is-X questions,\nanswer DIRECTLY \u2014 usually with ONE `codegraph_explore` call.\n`codegraph_explore` takes either a natural-language question or a bag of\nsymbol/file names and returns the verbatim source of the relevant symbols\ngrouped by file, so it is Read-equivalent and most often the ONLY\ncodegraph call you need. Codegraph IS the pre-built search index \u2014 so\ndelegating the lookup to a separate file-reading sub-task/agent, or\nrunning your own grep + read loop, repeats work codegraph already did and\ncosts more for the same answer. Reach for raw Read/Grep only to confirm a\nspecific detail codegraph didn't cover. A direct codegraph answer is\ntypically one to a few calls; a grep/read exploration is dozens.\n\n## Tool selection by intent\n\n- **Almost any question \u2014 \"how does X work\", architecture, a bug, \"what/where is X\", or surveying an area** \u2192 `codegraph_explore` (PRIMARY \u2014 call FIRST; ONE capped call returns the verbatim source of the relevant symbols grouped by file; most often the ONLY call you need)\n- **\"How does X reach/become Y? / the flow / the path from X to Y\"** \u2192 `codegraph_explore`, naming the symbols that span the flow (e.g. `mutateElement renderScene`) \u2014 it surfaces the call path among them, including dynamic-dispatch hops (callbacks, React re-render, JSX children) grep can't follow\n- **\"What is the symbol named X?\" (just its location)** \u2192 `codegraph_search`\n- **\"What calls this?\" / \"What does this call?\" / \"What would changing this break?\"** \u2192 `codegraph_callers` / `codegraph_callees` / `codegraph_impact`\n- **One specific symbol's full source (esp. a body `codegraph_explore` trimmed), or an OVERLOADED name** \u2192 `codegraph_node` (with `includeCode`): for an ambiguous name it returns EVERY matching definition's body in one call, so you never Read a file to find the right overload\n- **\"What's in directory X?\"** \u2192 `codegraph_files`\n- **\"Is the index ready / what's its size?\"** \u2192 `codegraph_status`\n\n## Common chains\n\n- **Flow / \"how does X reach Y\"**: ONE `codegraph_explore` with the symbol names spanning the flow \u2014 it surfaces the call path among them (riding dynamic-dispatch hops) AND returns their source. No need to reconstruct the path with `codegraph_search` + `codegraph_callers`.\n- **Onboarding / understanding any area**: ONE `codegraph_explore` is usually the whole answer. Only follow up \u2014 `codegraph_node` for a specific symbol \u2014 if something is still unclear.\n- **Refactor planning**: `codegraph_search` \u2192 `codegraph_callers` \u2192 `codegraph_impact`. The blast-radius answer comes from impact, not from walking callers manually.\n- **Debugging a regression**: `codegraph_callers` of the suspected symbol; widen with `codegraph_impact` if an unexpected call appears.\n\n## Anti-patterns\n\n- **Trust codegraph's results \u2014 don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.\n- **Don't grep first** when looking up a symbol by name \u2014 `codegraph_search` is faster and returns kind + location + signature.\n- **Don't chain `codegraph_search` + `codegraph_node`** to understand an area \u2014 ONE `codegraph_explore` returns the relevant symbols' source together in a single round-trip.\n- **Don't loop `codegraph_node` over many symbols** \u2014 one `codegraph_explore` call returns them all grouped by file, while each separate call re-reads the whole context and costs far more. Use `codegraph_node` for a single symbol.\n- **After editing, check the staleness banner.** When a tool response starts with \"\u26A0\uFE0F Some files referenced below were edited since the last index sync\u2026\", the listed files are pending re-index \u2014 Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust codegraph. `codegraph_status` also lists pending files under \"Pending sync\".\n\n## Limitations\n\n- If a tool reports the project isn't initialized, `.codegraph/` doesn't exist yet \u2014 offer to run `codegraph init -i` to build the index.\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.\n";
 //# sourceMappingURL=server-instructions.d.ts.map

package/dist/mcp/tools.d.ts

@@ -105,8 +105,9 @@ export interface ToolResult {
 /**
  * All CodeGraph MCP tools
  *
- * Designed for minimal context usage - use codegraph_context as the primary tool,
- * and only use other tools for targeted follow-up queries.
+ * Designed for minimal context usage - use codegraph_explore as the primary tool
+ * (one call usually answers the whole question), and only use other tools for
+ * targeted follow-up queries.
  *
  * All tools support cross-project queries via the optional `projectPath` parameter.
  */
@@ -158,7 +159,7 @@ export declare class ToolHandler {
      * Unset/empty → every tool is exposed. Lets an operator (or an A/B harness)
      * trim the tool surface without rebuilding the client config; the ablated
      * tool is then truly absent from ListTools rather than merely denied on call.
-     * Matching is on the short form, so "trace" and "codegraph_trace" both work.
+     * Matching is on the short form, so "node" and "codegraph_node" both work.
      */
     private toolAllowlist;
     /** Whether a tool name passes the CODEGRAPH_MCP_TOOLS allowlist (if any). */
@@ -240,27 +241,6 @@ export declare class ToolHandler {
      * Handle codegraph_search
      */
     private handleSearch;
-    /**
-     * Handle codegraph_context
-     */
-    private handleContext;
-    /**
-     * Detect a flow-style task ("how does X reach Y", "trace the path from A to B")
-     * and pre-run trace between the most likely endpoints, returning the trace
-     * body to splice into the context response. Returns '' for non-flow queries
-     * or when no plausible endpoint pair can be extracted.
-     *
-     * Conservative by design: only fires when the task has both a clear flow
-     * keyword AND at least two distinct PascalCase / camelCase identifiers.
-     * False positives waste a graph query; false negatives just fall back to
-     * the agent calling trace itself (existing path-proximity wiring handles
-     * disambiguation either way).
-     */
-    private maybeInlineFlowTrace;
-    /**
-     * Heuristic to detect if a query looks like a feature request
-     */
-    private looksLikeFeatureRequest;
     /**
      * Handle codegraph_callers
      */
@@ -273,18 +253,6 @@ export declare class ToolHandler {
      * Handle codegraph_impact
      */
     private handleImpact;
-    /**
-     * Handle codegraph_trace — shortest CALL PATH between two symbols.
-     *
-     * Exposes GraphTraverser.findPath: the chain of functions from `from` to `to`,
-     * each hop annotated with file:line and the call-site line. This is the
-     * capability grep/Read structurally cannot provide. When no static path
-     * exists, the chain has almost certainly broken at dynamic dispatch
-     * (callbacks, descriptors, metaclasses) — we say so and surface the start
-     * symbol's outgoing calls so the agent bridges the one missing hop with
-     * codegraph_node rather than blindly reading.
-     */
-    private handleTrace;
     /**
      * Describe a synthesized (dynamic-dispatch) edge for human output: how the
      * callback was wired up — the bridge static parsing can't see. Returns null
@@ -292,19 +260,6 @@ export declare class ToolHandler {
      * hop reads as "registered via onUpdate at App.tsx:3148", not a bare arrow.
      */
     private synthEdgeNote;
-    /**
-     * Read one trimmed source line at "relpath:line" (relative to the project
-     * root). `cache` holds split file contents so a multi-hop trace reads each
-     * file at most once. Returns null if the file/line can't be resolved.
-     */
-    private sourceLineAt;
-    /**
-     * Read a hop's body — filePath lines [startLine..endLine] — for inlining into
-     * a trace, capped (lines + chars) so the whole path stays path-scoped even on
-     * a 7-hop chain. Dedents to the body's own indentation and marks truncation.
-     * Shares `cache` with sourceLineAt so each file is read at most once per trace.
-     */
-    private sourceRangeAt;
     /**
      * Flow-from-named-symbols: an agent's codegraph_explore query is a bag of
      * symbol names that usually spans the flow it's investigating (e.g.
@@ -320,6 +275,32 @@ export declare class ToolHandler {
      * dropping unrelated `OmsOrderService::list`.
      */
     private buildFlowFromNamedSymbols;
+    /**
+     * Compact "blast radius" for the entry symbols of an explore result: who
+     * depends on each (callers) and which test files cover it — LOCATIONS ONLY,
+     * no source, so the agent knows what to update / re-verify before editing
+     * without reaching for a separate impact call. Always-on, but skips symbols
+     * that have no dependents (nothing to warn about), and returns '' when none
+     * qualify so a leaf-only exploration stays clean.
+     */
+    private buildBlastRadiusSection;
+    /**
+     * Graph-connectivity relevance via Random-Walk-with-Restart (personalized
+     * PageRank) from the query's matched SEED nodes over the call/reference graph.
+     *
+     * This is the ranking signal text search (FTS/bm25) CANNOT provide, and it's
+     * codegraph's home turf: relevance by STRUCTURE, not words. A file whose
+     * symbols are call-connected to the matched cluster accrues walk mass and
+     * ranks high; a lone TEXT match — e.g. `LensSwitcher.swift` matched the word
+     * "switch" from `switchOrganization`, but calls none of `setUser`/`fetchUser`
+     * — gets only its own restart probability and ranks ~0. Immune to the
+     * tokenization trap that fools term matching, deterministic, no embeddings.
+     *
+     * Undirected adjacency (reachability both ways), restart α=0.25 to the seeds,
+     * power iteration to convergence. Bounded to the already-relevant subgraph, so
+     * it's a few hundred nodes × ~25 iterations — negligible cost.
+     */
+    private computeGraphRelevance;
     /**
      * Handle codegraph_explore — deep exploration in a single call
      *
@@ -336,6 +317,8 @@ export declare class ToolHandler {
      * Handle codegraph_node
      */
     private handleNode;
+    /** Render one symbol: details + (optional) body/outline + its caller/callee trail. */
+    private renderNodeSection;
     /**
      * Build the "trail" for a symbol: its direct callees (what it calls) and
      * callers (what calls it), each with file:line — so codegraph_node doubles as
@@ -393,7 +376,15 @@ export declare class ToolHandler {
      *      Python — `stage_apply::run` matches a `run` in `stage_apply.rs`)
      */
     private matchesSymbol;
-    private findSymbol;
+    /**
+     * Find ALL definitions matching a name, ranked, so codegraph_node can return
+     * every overload instead of guessing one (the wrong guess → a Read). Keepers
+     * rank before generated stubs (.pb.go etc.); stable within a group preserves
+     * FTS order. Returns [] when nothing matches; a qualified lookup that finds no
+     * exact match returns [] rather than a misleading fuzzy file hit (#173); a
+     * bare name with no exact match falls back to the single top fuzzy result.
+     */
+    private findSymbolMatches;
     /**
      * Find ALL symbols matching a name. Used by callers/callees/impact to aggregate
      * results across all matching symbols (e.g., multiple classes with an `execute` method).
@@ -415,7 +406,6 @@ export declare class ToolHandler {
      */
     private buildContainerOutline;
     private formatNodeDetails;
-    private formatTaskContext;
     private textResult;
     private errorResult;
 }

package/dist/search/query-utils.d.ts

@@ -50,4 +50,22 @@ export declare function nameMatchBonus(nodeName: string, query: string): number;
  * Functions and classes are typically more relevant than variables/imports
  */
 export declare function kindBonus(kind: Node['kind']): number;
+/**
+ * Whether a query token looks like a code identifier the user deliberately typed
+ * (camelCase / PascalCase-with-internal-caps / snake_case / has a digit) rather
+ * than a plain dictionary word ("flat", "object", "screen").
+ *
+ * Used to decide whether an EXACT name match earns the "the user named this
+ * symbol" exemption from single-term dampening. A common English word that
+ * happens to exact-match an unrelated symbol — the query "flat object" matching
+ * a constant named `FLAT` — must NOT get that exemption, or the +exact-name
+ * bonus floats it to the top of a prose query on its own.
+ *
+ * Classifies the token AS THE USER TYPED IT, not the matched symbol's name:
+ * "flat" (lowercase, descriptive) is non-distinctive even though it matches
+ * `FLAT`. A leading-capital-only word ("Screen", "Zustand") is also treated as
+ * a plain word — sentence-start capitalization and proper nouns aren't reliable
+ * identifier signals.
+ */
+export declare function isDistinctiveIdentifier(token: string): boolean;
 //# sourceMappingURL=query-utils.d.ts.map

package/dist/types.d.ts

@@ -169,6 +169,14 @@ export interface Subgraph {
     edges: Edge[];
     /** Root node IDs (entry points) */
     roots: string[];
+    /**
+     * Retrieval confidence for context-style queries. `'low'` means the query
+     * resolved only to isolated common-word matches (no entry point corroborated
+     * by 2+ distinct query terms) — callers should surface an honest handoff to
+     * explore/trace rather than present the results as comprehensive. Undefined
+     * for graph traversals that don't run the search-ranking path.
+     */
+    confidence?: 'high' | 'low';
 }
 /**
  * Options for graph traversal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colbymchenry/codegraph",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "description": "Local-first code intelligence for AI agents (MCP). Self-contained — bundles its own runtime.",
   "bin": {
     "codegraph": "npm-shim.js"
@@ -15,12 +15,12 @@
     "./package.json": "./package.json"
   },
   "optionalDependencies": {
-    "@colbymchenry/codegraph-darwin-arm64": "0.9.8",
-    "@colbymchenry/codegraph-darwin-x64": "0.9.8",
-    "@colbymchenry/codegraph-linux-arm64": "0.9.8",
-    "@colbymchenry/codegraph-linux-x64": "0.9.8",
-    "@colbymchenry/codegraph-win32-arm64": "0.9.8",
-    "@colbymchenry/codegraph-win32-x64": "0.9.8"
+    "@colbymchenry/codegraph-darwin-arm64": "0.9.9",
+    "@colbymchenry/codegraph-darwin-x64": "0.9.9",
+    "@colbymchenry/codegraph-linux-arm64": "0.9.9",
+    "@colbymchenry/codegraph-linux-x64": "0.9.9",
+    "@colbymchenry/codegraph-win32-arm64": "0.9.9",
+    "@colbymchenry/codegraph-win32-x64": "0.9.9"
   },
   "files": [
     "npm-shim.js",