@colbymchenry/codegraph 0.9.7 → 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
 
-**~35% cheaper · ~70% fewer tool calls · 100% local**
+**~16% cheaper · ~58% fewer tool calls · 100% local**
 
 ### [Documentation & Website →](https://colbymchenry.github.io/codegraph/)
 
@@ -55,6 +55,8 @@ cd your-project
 codegraph init -i
 ```
 
+<sub>`codegraph init` just creates the local `.codegraph/` index directory; adding `-i` (`--index`) also builds the initial graph in the same step. Without `-i`, run `codegraph index` afterwards to populate it.</sub>
+
 <div align="center">
 
 ![1_C_VYnhpys0UHrOuOgpgoyw](https://github.com/user-attachments/assets/f168182f-4d9a-44e0-94d7-08d018cc8a3a)
@@ -81,26 +83,101 @@ 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 **v0.9.4** (2026-05-24)._
+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: 35% cheaper · 57% fewer tokens · 46% faster · 71% 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 | 26% cheaper | 78% fewer | 52% faster | 85% fewer |
-| **Excalidraw** | TypeScript · ~640 | 52% cheaper | 90% fewer | 73% faster | 96% fewer |
-| **Django** | Python · ~3k | 12% cheaper | 36% fewer | 19% faster | 53% fewer |
-| **Tokio** | Rust · ~790 | 82% cheaper | 86% fewer | 71% faster | 92% fewer |
-| **OkHttp** | Java · ~645 | 2% cheaper | 13% fewer | 31% faster | 45% fewer |
-| **Gin** | Go · ~110 | 21% cheaper | 34% fewer | 27% faster | 40% fewer |
-| **Alamofire** | Swift · ~110 | 47% cheaper | 64% fewer | 48% faster | 83% 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 **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>
+
+**VS Code** · ~10k files
+| Metric | WITH cg | WITHOUT cg | Δ |
+|---|---|---|---|
+| Time | 1m 59s | 2m 13s | 11% faster |
+| File Reads | 0 | 9 | −9 |
+| Grep/Bash | 0 | 11 | −11 |
+| 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 32s | 2m 6s | 27% faster |
+| File Reads | 0 | 7 | −7 |
+| 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 43s | 1m 58s | 13% faster |
+| File Reads | 0 | 9 | −9 |
+| Grep/Bash | 0 | 5 | −5 |
+| Tool calls | 3 | 13 | 77% fewer |
+| Total tokens | 559k | 1.41M | 60% fewer |
+| Cost | $0.57 | $0.62 | 8% cheaper |
+
+**Tokio** · ~790 files
+| Metric | WITH cg | WITHOUT cg | Δ |
+|---|---|---|---|
+| Time | 1m 55s | 2m 20s | 18% faster |
+| File Reads | 0 | 8 | −8 |
+| Grep/Bash | 0 | 6 | −6 |
+| 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 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 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 | 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 |
 
-The gains scale with codebase size: on large repos the agent answers from the index in a handful of calls with **zero file reads**, while the no-CodeGraph agent fans out across grep/find/Read (and the sub-agents it spawns). On a small repo like Gin (~150 files) native search is already cheap, so the margin narrows.
+</details>
 
 <details>
 <summary><strong>Full benchmark details</strong></summary>
 
-**Methodology.** Each arm is `claude -p` (Claude Opus 4.7) 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 on codegraph **v0.9.4** (2026-05-24); 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. Tokio's without-arm hit $2.41/3m 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 |
@@ -113,18 +190,7 @@ The gains scale with codebase size: on large repos the agent answers from the in
 | Gin | "How does gin route requests through its middleware chain?" |
 | Alamofire | "How does Alamofire build, send, and validate a request?" |
 
-**Raw medians — WITH → WITHOUT:**
-| Codebase | Cost | Tokens | Time | Tool calls |
-|----------|------|--------|------|------------|
-| VS Code | $0.60 → $0.80 | 601k → 2.8M | 1m 10s → 2m 26s | 8 → 55 |
-| Excalidraw | $0.43 → $0.90 | 344k → 3.5M | 48s → 2m 58s | 3 → 79 |
-| Django | $0.59 → $0.67 | 739k → 1.2M | 1m 19s → 1m 38s | 9 → 19 |
-| Tokio | $0.42 → $2.41 | 379k → 2.6M | 53s → 3m 2s | 4 → 53 |
-| OkHttp | $0.47 → $0.47 | 636k → 730k | 42s → 1m 1s | 6 → 11 |
-| Gin | $0.37 → $0.47 | 444k → 675k | 44s → 1m 0s | 6 → 10 |
-| Alamofire | $0.61 → $1.14 | 1.0M → 2.8M | 1m 17s → 2m 27s | 12 → 69 |
-
-**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 (and the Explore sub-agents it spawns) 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>
 
@@ -299,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",
@@ -319,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`.
 
@@ -344,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                      │
@@ -375,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)
@@ -419,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 |
 
@@ -434,8 +497,14 @@ When running as an MCP server, CodeGraph exposes these tools to Claude Code:
 
 ## Library Usage
 
+CodeGraph can be embedded directly. The npm package re-exports its programmatic
+API, so both `import` and `require` resolve the `CodeGraph` class in your own
+process — handy for embedding it in an app (e.g. an Electron main process).
+
 ```typescript
 import CodeGraph from '@colbymchenry/codegraph';
+// CommonJS works too:
+//   const { CodeGraph } = require('@colbymchenry/codegraph');
 
 const cg = await CodeGraph.init('/path/to/project');
 // Or: const cg = await CodeGraph.open('/path/to/project');
@@ -454,6 +523,21 @@ cg.unwatch(); // stop watching
 cg.close();
 ```
 
+Lower-level building blocks are exported from the same entry point for callers
+that drive the graph directly: `DatabaseConnection`, `QueryBuilder`,
+`getDatabasePath`, `initGrammars` / `loadGrammarsForLanguages`, and `FileLock`.
+
+**Embedding requirements**
+
+- Install from npm (`npm i @colbymchenry/codegraph`) so the matching
+  per-platform package — which carries the compiled library and its
+  dependencies — is fetched alongside the shim.
+- The API runs on **your** runtime, so it needs **Node 22.5+** for the built-in
+  `node:sqlite` (Electron qualifies when its bundled Node is 22.5+). The CLI and
+  MCP server are unaffected — they run on the self-contained bundled runtime.
+- TypeScript types ship with the package. As with any Node-targeting library,
+  keep `@types/node` available and `skipLibCheck: true` (the common default).
+
 ---
 
 ## Configuration

package/dist/bin/codegraph.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * CodeGraph CLI
+ *
+ * Command-line interface for CodeGraph code intelligence.
+ *
+ * Usage:
+ *   codegraph                    Run interactive installer (when no args)
+ *   codegraph install            Run interactive installer
+ *   codegraph uninstall          Remove CodeGraph from your agents
+ *   codegraph init [path]        Initialize CodeGraph in a project
+ *   codegraph uninit [path]      Remove CodeGraph from a project
+ *   codegraph index [path]       Index all files in the project
+ *   codegraph sync [path]        Sync changes since last index
+ *   codegraph status [path]      Show index status
+ *   codegraph query <search>     Search for symbols
+ *   codegraph files [options]    Show project file structure
+ *   codegraph context <task>     Build context for a task
+ *   codegraph callers <symbol>   Find what calls a function/method
+ *   codegraph callees <symbol>   Find what a function/method calls
+ *   codegraph impact <symbol>    Analyze what code is affected by changing a symbol
+ *   codegraph affected [files]   Find test files affected by changes
+ */
+export {};
+//# sourceMappingURL=codegraph.d.ts.map

package/dist/bin/node-version-check.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Node.js version compatibility check.
+ *
+ * Node 25.x has a V8 turboshaft WASM JIT Zone allocator bug that
+ * reliably crashes CodeGraph with `Fatal process out of memory: Zone`
+ * during tree-sitter grammar compilation. This module owns the
+ * user-facing banner shown before exit. Kept side-effect-free so it's
+ * safe to import from tests without triggering CLI bootstrap.
+ */
+/**
+ * Build the bordered banner shown when CodeGraph detects an
+ * unsupported Node.js major version (currently 25+). Pinned via unit
+ * test so the recovery commands and override instructions can't be
+ * silently stripped by future edits.
+ *
+ * Uses ASCII glyphs to stay readable on Windows OEM-codepage consoles
+ * (see ../ui/glyphs.ts for the rationale).
+ */
+export declare function buildNode25BlockBanner(nodeVersion: string): string;
+/**
+ * Lowest supported Node.js major version. Matches the `engines` floor in
+ * package.json. Below this, CodeGraph relies on language features / native APIs
+ * that aren't present, and the combination is untested. `engines` alone only
+ * *warns* on install (unless the user set `engine-strict`), so the CLI bootstrap
+ * also hard-blocks here to actually enforce the floor.
+ */
+export declare const MIN_NODE_MAJOR = 20;
+/**
+ * Build the bordered banner shown when CodeGraph detects a Node.js major below
+ * {@link MIN_NODE_MAJOR}. Pinned via unit test so the recovery commands and the
+ * override env var can't be silently stripped by future edits.
+ *
+ * Uses ASCII glyphs to stay readable on Windows OEM-codepage consoles
+ * (see ../ui/glyphs.ts for the rationale).
+ */
+export declare function buildNodeTooOldBanner(nodeVersion: string): string;
+//# sourceMappingURL=node-version-check.d.ts.map

package/dist/bin/uninstall.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * CodeGraph preuninstall cleanup script
+ *
+ * Runs automatically when `npm uninstall -g @colbymchenry/codegraph`
+ * is called. Loops over every known agent target's `uninstall(loc)`
+ * for the global location only — local-location entries live inside
+ * project working trees and aren't ours to nuke at npm-uninstall
+ * time.
+ *
+ * This script must never throw — a failed cleanup must not block
+ * uninstall.
+ */
+//# sourceMappingURL=uninstall.d.ts.map

package/dist/context/formatter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Context Formatter
+ *
+ * Formats TaskContext as markdown or JSON for consumption by Claude.
+ */
+import { Node, TaskContext, Subgraph } from '../types';
+/**
+ * Format context as markdown
+ *
+ * Creates a compact markdown document optimized for Claude with minimal context usage:
+ * - Brief summary
+ * - Entry points with locations
+ * - Code blocks only for key symbols
+ */
+export declare function formatContextAsMarkdown(context: TaskContext): string;
+/**
+ * Format context as JSON
+ *
+ * Returns a structured JSON representation suitable for programmatic use.
+ */
+export declare function formatContextAsJson(context: TaskContext): string;
+/**
+ * Format a subgraph as an ASCII tree structure
+ */
+export declare function formatSubgraphTree(subgraph: Subgraph, entryPoints: Node[]): string;
+/**
+ * Format bytes as human-readable string
+ */
+export declare function formatBytes(bytes: number): string;
+//# sourceMappingURL=formatter.d.ts.map

package/dist/context/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Context Builder
+ *
+ * Builds rich context for tasks by combining FTS search with graph traversal.
+ * Outputs structured context ready to inject into Claude.
+ */
+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
+ *
+ * Coordinates semantic search and graph traversal to build
+ * comprehensive context for tasks.
+ */
+export declare class ContextBuilder {
+    private projectRoot;
+    private queries;
+    private traverser;
+    constructor(projectRoot: string, queries: QueryBuilder, traverser: GraphTraverser);
+    /**
+     * Build context for a task
+     *
+     * Pipeline:
+     * 1. Parse task input (string or {title, description})
+     * 2. Run semantic search to find entry points
+     * 3. Expand graph around entry points
+     * 4. Extract code blocks for key nodes
+     * 5. Format output for Claude
+     *
+     * @param input - Task description or object with title/description
+     * @param options - Build options
+     * @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).
+     *
+     * This bakes the value of path-finding INTO the always-loaded `context` tool.
+     * Agents reliably read context's output but do NOT discover/adopt a standalone
+     * trace tool (in deferred-MCP harnesses they only ToolSearch-select tools they
+     * already know). Delivering the flow here means "how does X reach Y" is
+     * answered without the agent needing to find, load, or choose a new tool.
+     * Chains stop where the static call graph ends (e.g. dynamic dispatch) — that
+     * truncation is honest, and the agent can codegraph_node the last hop to bridge.
+     */
+    private buildCallPathsSection;
+    /**
+     * Find relevant subgraph for a query
+     *
+     * Uses hybrid search combining exact symbol lookup with semantic search:
+     * 1. Extract potential symbol names from query
+     * 2. Look up exact matches for those symbols (high confidence)
+     * 3. Use semantic search for concept matching
+     * 4. Merge results, prioritizing exact matches
+     * 5. Traverse graph from entry points
+     *
+     * @param query - Natural language query
+     * @param options - Search and traversal options
+     * @returns Subgraph of relevant nodes and edges
+     */
+    findRelevantContext(query: string, options?: FindRelevantContextOptions): Promise<Subgraph>;
+    /**
+     * Get the source code for a node
+     *
+     * Reads the file and extracts the code between startLine and endLine.
+     *
+     * @param nodeId - ID of the node
+     * @returns Code string or null if not found
+     */
+    getCode(nodeId: string): Promise<string | null>;
+    /**
+     * Extract code from a node's source file
+     */
+    private extractNodeCode;
+    /**
+     * Get entry points from a subgraph (the root nodes)
+     */
+    private getEntryPoints;
+    /**
+     * Extract code blocks for key nodes in the subgraph
+     */
+    private extractCodeBlocks;
+    /**
+     * Get unique files from a subgraph
+     */
+    private getRelatedFiles;
+    /**
+     * Generate a summary of the context
+     */
+    private generateSummary;
+    /**
+     * Resolve import/export nodes to their actual definitions
+     *
+     * When search returns `import { TerminalPanel }`, users want the TerminalPanel
+     * class definition, not the import statement. This follows the `imports` edge
+     * to find and return the actual definition instead.
+     *
+     * @param results - Search results that may include import/export nodes
+     * @returns Results with imports resolved to definitions where possible
+     */
+    private resolveImportsToDefinitions;
+}
+/**
+ * Create a context builder
+ */
+export declare function createContextBuilder(projectRoot: string, queries: QueryBuilder, traverser: GraphTraverser): ContextBuilder;
+export { formatContextAsMarkdown, formatContextAsJson } from './formatter';
+//# sourceMappingURL=index.d.ts.map

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/db/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Database Layer
+ *
+ * Handles SQLite database initialization and connection management.
+ */
+import { SqliteDatabase, SqliteBackend } from './sqlite-adapter';
+import { SchemaVersion } from '../types';
+export { SqliteDatabase, SqliteBackend } from './sqlite-adapter';
+/**
+ * Database connection wrapper with lifecycle management
+ */
+export declare class DatabaseConnection {
+    private db;
+    private dbPath;
+    private backend;
+    private constructor();
+    /**
+     * Initialize a new database at the given path
+     */
+    static initialize(dbPath: string): DatabaseConnection;
+    /**
+     * Open an existing database
+     */
+    static open(dbPath: string): DatabaseConnection;
+    /**
+     * Get the underlying database instance
+     */
+    getDb(): SqliteDatabase;
+    /**
+     * Get the SQLite backend serving this connection. Per-instance so
+     * MCP cross-project queries report the right backend even when
+     * multiple project DBs are open in the same process.
+     */
+    getBackend(): SqliteBackend;
+    /**
+     * Get database file path
+     */
+    getPath(): string;
+    /**
+     * The journal mode actually in effect (e.g. 'wal', 'delete').
+     *
+     * SQLite silently keeps the prior mode if WAL can't be enabled — e.g. on
+     * filesystems without shared-memory support (some network/virtualized mounts,
+     * WSL2 /mnt), and always on the wasm backend. So the effective mode can differ
+     * from what `configureConnection` requested. Surfaced in `codegraph status` so
+     * a "database is locked" report is triageable: 'wal' ⇒ readers never block on a
+     * writer; anything else ⇒ they can. See issue #238.
+     */
+    getJournalMode(): string;
+    /**
+     * Get current schema version
+     */
+    getSchemaVersion(): SchemaVersion | null;
+    /**
+     * Execute a function within a transaction
+     */
+    transaction<T>(fn: () => T): T;
+    /**
+     * Get database file size in bytes
+     */
+    getSize(): number;
+    /**
+     * Optimize database (vacuum and analyze)
+     */
+    optimize(): void;
+    /**
+     * Lightweight, non-blocking maintenance to run after bulk writes
+     * (indexAll, sync). Two operations:
+     *
+     *   - `PRAGMA optimize` — incremental ANALYZE; SQLite only re-analyzes
+     *     tables whose row counts changed materially since the last
+     *     ANALYZE. Without it, the query planner has no statistics on the
+     *     freshly-bulk-loaded tables and can pick suboptimal indexes.
+     *
+     *   - `PRAGMA wal_checkpoint(PASSIVE)` — fold pending WAL pages back
+     *     into the main database file so the WAL file doesn't grow
+     *     unboundedly between automatic checkpoints (auto-fires at 1000
+     *     pages by default; large indexAll runs blow past that).
+     *
+     * Both operations are silently swallowed on failure — they're a
+     * best-effort optimization, never load-bearing for correctness.
+     */
+    runMaintenance(): void;
+    /**
+     * Close the database connection
+     */
+    close(): void;
+    /**
+     * Check if the database connection is open
+     */
+    isOpen(): boolean;
+}
+/**
+ * Default database filename
+ */
+export declare const DATABASE_FILENAME = "codegraph.db";
+/**
+ * Get the default database path for a project
+ */
+export declare function getDatabasePath(projectRoot: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/db/migrations.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Database Migrations
+ *
+ * Schema versioning and migration support.
+ */
+import { SqliteDatabase } from './sqlite-adapter';
+/**
+ * Current schema version
+ */
+export declare const CURRENT_SCHEMA_VERSION = 4;
+/**
+ * Migration definition
+ */
+interface Migration {
+    version: number;
+    description: string;
+    up: (db: SqliteDatabase) => void;
+}
+/**
+ * Get the current schema version from the database
+ */
+export declare function getCurrentVersion(db: SqliteDatabase): number;
+/**
+ * Run all pending migrations
+ */
+export declare function runMigrations(db: SqliteDatabase, fromVersion: number): void;
+/**
+ * Check if the database needs migration
+ */
+export declare function needsMigration(db: SqliteDatabase): boolean;
+/**
+ * Get list of pending migrations
+ */
+export declare function getPendingMigrations(db: SqliteDatabase): Migration[];
+/**
+ * Get migration history from database
+ */
+export declare function getMigrationHistory(db: SqliteDatabase): Array<{
+    version: number;
+    appliedAt: number;
+    description: string | null;
+}>;
+export {};
+//# sourceMappingURL=migrations.d.ts.map