From 2f3188eb496dcc6936c06a588a072410435e22e8 Mon Sep 17 00:00:00 2001 From: Colby McHenry Date: Mon, 22 Jun 2026 09:45:57 -0500 Subject: [PATCH] docs: reframe value prop around precision/speed, update Node floor to 20, and expand language/framework coverage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Benchmark table reordered to lead with tool calls, time, and file reads (the universal wins); cost and tokens moved right with a note that savings are scale-dependent, not a headline claim - README/introduction/quickstart/installation messaging updated to "surgical context · fewer tool calls · faster answers" framing, dropping the "16% cheaper" headline - Node engine floor raised from 18 to 20 in CLAUDE.md, package.json description updated - `codegraph init` now creates and indexes in one step; the `-i` flag is retired (still accepted as a no-op) - CLI reference expanded with new commands: `explore`, `node`, `unlock`, `daemon`, `telemetry`, `upgrade`, `version`, `help` - MCP server docs clarified: single `codegraph_explore` tool exposed by default, others unlisted but re-enableable via `CODEGRAPH_MCP_TOOLS` - Language support adds Objective-C, Astro, and R; framework routes adds Play, Vue Router/Nuxt, and Astro - API reference documents lower-level exports and embedding requirements (Node 22.5+ for `node:sqlite`) - Troubleshooting adds WSL/Windows dual-checkout guidance - How-it-works updated: SQLite backend is now Node's built-in `node:sqlite` in WAL mode, not better-sqlite3/WASM --- CLAUDE.md | 2 +- README.md | 36 ++++++++++--------- package.json | 2 +- .../docs/core-concepts/how-it-works.md | 2 +- .../content/docs/core-concepts/resolution.md | 2 +- .../docs/getting-started/installation.md | 9 ++--- .../docs/getting-started/introduction.md | 15 ++++---- .../docs/getting-started/quickstart.md | 19 +++++----- .../docs/getting-started/your-first-graph.md | 19 ++++++---- .../content/docs/guides/framework-routes.md | 17 +++++---- site/src/content/docs/guides/indexing.md | 6 ++-- site/src/content/docs/reference/api.md | 24 +++++++++++++ site/src/content/docs/reference/cli.md | 30 +++++++++++----- .../content/docs/reference/integrations.md | 14 +++----- site/src/content/docs/reference/languages.md | 3 ++ site/src/content/docs/reference/mcp-server.md | 31 +++++++++++----- site/src/content/docs/troubleshooting.md | 8 +++-- 17 files changed, 156 insertions(+), 83 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 6fe116d..dfb1f07 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,7 +29,7 @@ npx vitest run __tests__/extraction.test.ts -t "TypeScript" `copy-assets` (called from `build`) copies `src/db/schema.sql` and all `src/extraction/wasm/*.wasm` files into `dist/`. **Any new SQL or grammar wasm must be copied or it won't ship.** -Node engines: `>=18.0.0 <25.0.0`. There is a hard exit on Node 25.x (see `src/bin/node-version-check.ts`). +Node engines: `>=20.0.0 <25.0.0`. There is a hard exit on Node 25.x and below 20 (see `src/bin/node-version-check.ts`). ## Architecture diff --git a/README.md b/README.md index fc4daa4..e772527 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Follow [@getcodegraph](https://x.com/getcodegraph) on X for updates. ### Supercharge Claude Code, Cursor, Codex, OpenCode, Hermes Agent, Gemini, Antigravity, and Kiro with Semantic Code Intelligence -**~16% cheaper · ~58% fewer tool calls · 100% local** +**Surgical context · fewer tool calls · faster answers · 100% local** ### [Documentation & Website →](https://colbymchenry.github.io/codegraph/) @@ -111,27 +111,31 @@ codegraph uninstall ## Why CodeGraph? -When Claude Code explores a codebase, it spawns **Explore agents** that scan files with grep, glob, and Read — consuming tokens on every tool call. +When an AI agent needs to understand code — to answer a question or make a change — it discovers structure the slow way: grep, glob, and Read, one file at a time, rebuilding call paths and dependencies by hand. That's a pile of tool calls and round-trips before it even starts the real work. -**CodeGraph gives those agents a pre-indexed knowledge graph** — symbol relationships, call graphs, and code structure. Agents query the graph instantly instead of scanning files. +**CodeGraph hands the agent the exact code it needs in one call.** It's a pre-built knowledge graph of every symbol, call edge, and dependency in your codebase — so instead of crawling files, the agent asks one question and gets back the relevant source, the call paths between those symbols (including dynamic-dispatch hops grep can't follow), and the blast radius of a change. **Surgical context, not a file-by-file search** — which means fewer tool calls and faster answers on every codebase, large or small. + +> **A note on cost:** CodeGraph's win on *every* codebase is precision and speed — fewer tool calls, faster answers. It cuts token and dollar cost too, but those savings are **scale-dependent**: small and noisy on a modest codebase, and material only once a repo is large and tangled — at the scale of a Google or Microsoft monorepo, multiplied by a whole team's daily agent usage — for them to compound into a real line item. On a 500-file project, adopt CodeGraph for the speed; the cost savings show up when the codebase (and the team) gets big. ### 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-06-02), on the current build (`codegraph_explore` as the primary tool)._ +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, 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: 16% cheaper · 47% fewer tokens · 22% faster · 58% fewer tool calls** +> **The universal win — every repo, every size: 58% fewer tool calls · 22% faster · file reads cut to ~zero.** -| Codebase | Language | Cost | Tokens | Time | Tool calls | -|----------|----------|------|--------|------|------------| -| **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 | +The reliable, universal payoff is **surgical context and speed**: CodeGraph collapses the agent's grep/find/Read crawl into a few direct queries — returning the exact methods you asked about even when they're buried in a multi-thousand-line file — so it answers with **near-zero file reads** while the no-CodeGraph agent spends its budget on discovery. The **Tokens** and **Cost** columns are real too, but — as noted above — they're **scale-dependent**: small and noisy per query, compounding into real money only at large-codebase, high-volume scale. -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. +| Codebase | Language | Tool calls | Time | File reads | Tokens | Cost | +|----------|----------|------------|------|------------|--------|------| +| **VS Code** | TypeScript · ~10k files | 81% fewer | 11% faster | 0 vs 9 | 64% fewer | 18% cheaper | +| **Excalidraw** | TypeScript · ~640 | 40% fewer | 27% faster | 0 vs 7 | 25% fewer | even | +| **Django** | Python · ~3k | 77% fewer | 13% faster | 0 vs 9 | 60% fewer | 8% cheaper | +| **Tokio** | Rust · ~790 | 57% fewer | 18% faster | 0 vs 8 | 38% fewer | even | +| **OkHttp** | Java · ~645 | 50% fewer | 31% faster | 0 vs 4 | 54% fewer | 25% cheaper | +| **Gin** | Go · ~110 | 44% fewer | 24% faster | 1 vs 6 | 23% fewer | 19% cheaper | +| **Alamofire** | Swift · ~110 | 58% fewer | 33% faster | 0 vs 9 | 64% fewer | 40% cheaper | + +**File reads** = median files the agent opened **with** vs **without** CodeGraph — the surgical-context win in one column. **Tokens** and **Cost** are the same with-vs-without deltas; they're directional (they move run-to-run) and, per query, small in absolute terms — which is why they only become a line item at scale. `codegraph_explore` also collapses redundant interchangeable implementations to signatures, so a response is sized to the *answer* rather than the file count.
Per-repo breakdown — WITH vs WITHOUT (median of 4) @@ -234,7 +238,7 @@ CodeGraph cuts **tokens, tool calls, and wall-clock time on every repo** — acr | | | |---|---| -| **Smart Context Building** | One tool call returns entry points, related symbols, and code snippets — no expensive exploration agents | +| **Surgical Context** | One tool call returns entry points, related symbols, and code snippets — no slow file-by-file exploration | | **Full-Text Search** | Find code by name instantly across your entire codebase, powered by FTS5 | | **Impact Analysis** | Trace callers, callees, and the full impact radius of any symbol before making changes | | **Always Fresh** | File watcher uses native OS events (FSEvents/inotify/ReadDirectoryChangesW) with debounced auto-sync — the graph stays current as you code, zero config | diff --git a/package.json b/package.json index a802f79..5caf75d 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "@colbymchenry/codegraph", "version": "1.0.1", - "description": "Supercharge Claude Code with semantic code intelligence. 94% fewer tool calls • 77% faster exploration • 100% local.", + "description": "Supercharge AI coding agents with semantic code intelligence — surgical context, fewer tool calls, faster answers. 100% local.", "main": "dist/index.js", "types": "dist/index.d.ts", "bin": { diff --git a/site/src/content/docs/core-concepts/how-it-works.md b/site/src/content/docs/core-concepts/how-it-works.md index ee5aaed..58d3c82 100644 --- a/site/src/content/docs/core-concepts/how-it-works.md +++ b/site/src/content/docs/core-concepts/how-it-works.md @@ -21,7 +21,7 @@ files → Extraction (tree-sitter) → DB (nodes/edges/files) ## 2. Storage -Everything goes into a local SQLite database (`.codegraph/codegraph.db`) with FTS5 full-text search. CodeGraph uses native `better-sqlite3` when available and transparently falls back to a WASM backend; `codegraph status` shows which is live. +Everything goes into a local SQLite database (`.codegraph/codegraph.db`) with FTS5 full-text search, using Node's built-in `node:sqlite` in WAL mode from the bundled runtime. ## 3. Resolution diff --git a/site/src/content/docs/core-concepts/resolution.md b/site/src/content/docs/core-concepts/resolution.md index 444b29f..d560e50 100644 --- a/site/src/content/docs/core-concepts/resolution.md +++ b/site/src/content/docs/core-concepts/resolution.md @@ -25,6 +25,6 @@ Static parsing misses computed and indirect calls, so flows can break at dynamic - `EventEmitter` channels - React re-render (`setState` → `render`) - JSX child (`render` → child component) -- Django ORM descriptors +- Interface → implementation dispatch Every synthesized edge is marked `provenance: 'heuristic'` with the site that wired it, and is shown inline wherever a path crosses it. diff --git a/site/src/content/docs/getting-started/installation.md b/site/src/content/docs/getting-started/installation.md index 4e8a0e2..4f9b909 100644 --- a/site/src/content/docs/getting-started/installation.md +++ b/site/src/content/docs/getting-started/installation.md @@ -14,9 +14,10 @@ The installer will: - Ask which agent(s) to configure — auto-detecting installed ones from **Claude Code**, **Cursor**, **Codex CLI**, **opencode**, **Hermes Agent**, **Gemini CLI**, **Antigravity IDE**, and **Kiro**. - Prompt to install `codegraph` on your `PATH` (so agents can launch the MCP server). - Ask whether configs apply to all your projects or just this one. -- Write each chosen agent's MCP server config plus an instructions file (e.g. `CLAUDE.md`, `.cursor/rules/codegraph.mdc`, `~/.codex/AGENTS.md`). +- Write each chosen agent's MCP server config, plus a small marker-fenced CodeGraph section in the agent's instructions file (`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`). Cursor and Kiro get the MCP config only. Removed cleanly by `codegraph uninstall`. - Set up auto-allow permissions when Claude Code is one of the targets. -- Initialize your current project (local installs only). + +The installer **wires up your agents only — it does not index your code.** After it finishes, build each project's graph yourself with `codegraph init` (step 3 below). ## Non-interactive (scripting / CI) @@ -43,10 +44,10 @@ Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent / ```bash cd your-project -codegraph init -i +codegraph init ``` -This builds the per-project knowledge graph index and wires up any project-local agent surfaces, so a single global `codegraph install` works in every project you open. +`codegraph init` creates the local `.codegraph/` directory and builds the full graph in the same step — one command. A single global `codegraph install` covers every project; you run `codegraph init` once per project. ## Supported platforms diff --git a/site/src/content/docs/getting-started/introduction.md b/site/src/content/docs/getting-started/introduction.md index 0550858..44d6546 100644 --- a/site/src/content/docs/getting-started/introduction.md +++ b/site/src/content/docs/getting-started/introduction.md @@ -1,6 +1,6 @@ --- title: Introduction -description: What CodeGraph is, and why it makes AI coding agents faster and cheaper. +description: What CodeGraph is, and why it makes AI coding agents faster and more precise. --- CodeGraph is a **local-first code-intelligence tool**. It parses your codebase with [tree-sitter](https://tree-sitter.github.io/), stores every symbol, edge, and file in a local SQLite database, and exposes the result as a queryable **knowledge graph** — over the [Model Context Protocol (MCP)](/codegraph/reference/mcp-server/), a CLI, and a TypeScript library. @@ -9,16 +9,15 @@ It exists to make AI coding agents — Claude Code, Cursor, Codex CLI, opencode, ## Why it matters -When an agent explores a codebase, it spends most of its budget on *discovery* — finding the right files before it can read them. CodeGraph removes that step: symbol relationships, call graphs, and structure are already indexed. +When an agent explores a codebase, it spends most of its budget on *discovery* — finding the right files before it can read them. CodeGraph removes that step: it hands the agent the exact code it needs in one call, so symbol relationships, call graphs, and structure don't have to be rebuilt file by file. -Tested across 7 real-world open-source codebases (median of 4 runs per arm), giving an agent CodeGraph was on average: +The universal win is **surgical context and speed** — fewer tool calls, faster answers, on every codebase. Tested across 7 real-world open-source codebases (median of 4 runs per arm), giving an agent CodeGraph meant, regardless of repo size: -- **35% cheaper** -- **57% fewer tokens** -- **46% faster** -- **71% fewer tool calls** +- **58% fewer tool calls** +- **22% faster** +- **file reads cut to ~zero** -The gains scale with codebase size — on large repos the agent answers from the index with **zero file reads**. +Token and dollar savings are real too, but they're the **scale-dependent bonus** that shows up on large, tangled codebases run at volume — small and noisy on a modest repo, material only once the codebase (and the team) gets big. ## What's in the graph diff --git a/site/src/content/docs/getting-started/quickstart.md b/site/src/content/docs/getting-started/quickstart.md index 1d63bb4..e1ea543 100644 --- a/site/src/content/docs/getting-started/quickstart.md +++ b/site/src/content/docs/getting-started/quickstart.md @@ -5,7 +5,9 @@ description: Get up and running with CodeGraph in seconds. Get up and running with CodeGraph in seconds. -## No Node.js required — one command grabs the right build for your OS +## 1. Install the CLI + +No Node.js required — one command grabs the right build for your OS: ```bash # macOS / Linux @@ -15,22 +17,23 @@ curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex ``` -## Already have Node? Use npm instead (works on any version) +Already have Node? `npm i -g @colbymchenry/codegraph` works on any version. CodeGraph bundles its own runtime — nothing to compile, no native build, works the same everywhere. The installer puts `codegraph` on your `PATH` but doesn't change your current shell — open a new terminal before the next step. + +## 2. Wire up your agent(s) ```bash -npx @colbymchenry/codegraph # zero-install, or: -npm i -g @colbymchenry/codegraph +codegraph install ``` -CodeGraph bundles its own runtime — nothing to compile, no native build, works the same everywhere. The interactive installer auto-configures your agent(s) — Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro. +Auto-detects and configures Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, and Kiro — wiring the CodeGraph MCP server into each. This step connects your agents only; it does **not** index any code. (Shortcut: `npx @colbymchenry/codegraph` downloads and runs the installer in one go.) -## Initialize Projects +## 3. Initialize each project ```bash cd your-project -codegraph init -i +codegraph init ``` -That's it — your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists. +`codegraph init` creates the local `.codegraph/` directory and builds the full graph in the same step — one command, done. Your agent will use CodeGraph tools automatically when a `.codegraph/` directory exists. Next: build [Your First Graph](/codegraph/getting-started/your-first-graph/), or see the full [Installation](/codegraph/getting-started/installation/) options. diff --git a/site/src/content/docs/getting-started/your-first-graph.md b/site/src/content/docs/getting-started/your-first-graph.md index 916edbd..5d3e784 100644 --- a/site/src/content/docs/getting-started/your-first-graph.md +++ b/site/src/content/docs/getting-started/your-first-graph.md @@ -3,19 +3,19 @@ title: Your First Graph description: Build an index and run your first queries against it. --- -Once CodeGraph is installed, building and exploring a graph takes three commands. +Once CodeGraph is installed, building and exploring a graph takes a few commands. ## Index a project ```bash cd your-project -codegraph init -i # initialize + index in one step +codegraph init ``` -`init` creates the `.codegraph/` directory; `-i` (or `--index`) immediately builds the full index. For an existing project you can re-index any time: +`codegraph init` creates the `.codegraph/` directory and builds the full graph in the same step — one command, done. From there a native file watcher keeps the index in sync on every change, so you rarely need to rebuild by hand. When you do want to: ```bash -codegraph index # full index +codegraph index # full re-index codegraph sync # incremental update of changed files ``` @@ -29,15 +29,22 @@ This reports the node/edge/file counts, the active SQLite backend, and the journ ## Run a query +Reach for `codegraph explore` first — a natural-language question or a bag of symbol names returns the relevant source plus the call paths between those symbols in a single shot (the same output the `codegraph_explore` tool gives your agent): + +```bash +codegraph explore "how does login work" +``` + +For narrower, scriptable lookups there are focused commands: + ```bash codegraph query UserService # find symbols by name codegraph callers handleRequest # what calls a function codegraph callees handleRequest # what a function calls codegraph impact AuthMiddleware # what a change would affect -codegraph context "fix the login flow" # build task-focused context ``` -Each accepts `--json` for machine-readable output. See the full [CLI reference](/codegraph/reference/cli/). +These four each accept `--json` for machine-readable output. See the full [CLI reference](/codegraph/reference/cli/). ## Hand it to your agent diff --git a/site/src/content/docs/guides/framework-routes.md b/site/src/content/docs/guides/framework-routes.md index 3d7fa91..05b1d58 100644 --- a/site/src/content/docs/guides/framework-routes.md +++ b/site/src/content/docs/guides/framework-routes.md @@ -8,18 +8,21 @@ CodeGraph detects web-framework routing files and emits `route` nodes linked by | Framework | Shapes recognized | |---|---| | **Django** | `path()`, `re_path()`, `url()`, `include()` in `urls.py` (CBV `.as_view()`, dotted paths) | -| **Flask** | `@app.route('/path', methods=[…])`, blueprint routes | -| **FastAPI** | `@app.get(…)`, `@router.post(…)`, all standard methods | -| **Express** | `app.get(…)`, `router.post(…)` with middleware chains | -| **NestJS** | `@Controller` + `@Get/@Post/…`, GraphQL resolvers, message/event patterns, WebSocket subscriptions | +| **Flask** | `@app.route('/path', methods=[...])`, blueprint routes | +| **FastAPI** | `@app.get(...)`, `@router.post(...)`, all standard methods | +| **Express** | `app.get(...)`, `router.post(...)` with middleware chains | +| **NestJS** | `@Controller` + `@Get/@Post/...`, GraphQL `@Resolver` + `@Query/@Mutation`, `@MessagePattern`/`@EventPattern`, `@SubscribeMessage` | | **Laravel** | `Route::get()`, `Route::resource()`, `Controller@action`, tuple syntax | -| **Drupal** | `*.routing.yml` routes; `hook_*` implementations in `.module`/`.theme`/`.install`/`.inc` | -| **Rails** | `get '/x', to: 'users#index'`, hash-rocket syntax | +| **Drupal** | `*.routing.yml` routes (`_controller`, `_form`, entity handlers); `hook_*` implementations in `.module`/`.theme`/`.install`/`.inc` | +| **Rails** | `get '/x', to: 'users#index'`, hash-rocket `=>` syntax | | **Spring** | `@GetMapping`, `@PostMapping`, `@RequestMapping` on methods | -| **Gin / chi / gorilla / mux** | `r.GET(…)`, `router.HandleFunc(…)` | +| **Play** | `GET`/`POST`/… verb routes in `conf/routes` → `Controller.method` actions (Scala + Java) | +| **Gin / chi / gorilla / mux** | `r.GET(...)`, `router.HandleFunc(...)` | | **Axum / actix / Rocket** | `.route("/x", get(handler))` | | **ASP.NET** | `[HttpGet("/x")]` attributes on action methods | | **Vapor** | `app.get("x", use: handler)` | | **React Router** / **SvelteKit** | Route component nodes | +| **Vue Router** / **Nuxt** | `pages/` file-based routes, `server/api/` endpoints, route middleware | +| **Astro** | `src/pages/` file-based routes (`.astro` pages + `.ts` endpoints, `[param]`/`[...rest]` syntax) | Route resolution is automatic — there's nothing to configure. If a framework file is recognized, its routes appear in the graph after the next index or sync. diff --git a/site/src/content/docs/guides/indexing.md b/site/src/content/docs/guides/indexing.md index 7c0fd1d..1518c3d 100644 --- a/site/src/content/docs/guides/indexing.md +++ b/site/src/content/docs/guides/indexing.md @@ -7,10 +7,10 @@ description: Full index, incremental sync, and the file watcher. ```bash cd your-project -codegraph init -i # initialize + full index +codegraph init # creates .codegraph/ and builds the full graph — one step ``` -`init` creates `.codegraph/`; `-i`/`--index` builds the index immediately. To initialize without indexing, drop the flag and run `codegraph index` later. +`codegraph init` creates the local `.codegraph/` directory and builds the full graph in the same step — one command, done. There's no separate index step to run afterward, and from here the graph [stays fresh automatically](#stay-fresh-automatically). ## Full vs. incremental @@ -20,7 +20,7 @@ codegraph index --force # re-index from scratch codegraph sync # incremental — only changed files ``` -`sync` is fast because it only reparses what changed. Use it after a branch switch or a batch of edits. +`sync` is fast because it only reparses what changed — it's what the file watcher runs for you on every edit (see [Stay fresh automatically](#stay-fresh-automatically)). You rarely need to run it by hand. ## Stay fresh automatically diff --git a/site/src/content/docs/reference/api.md b/site/src/content/docs/reference/api.md index 9c896a7..173ab21 100644 --- a/site/src/content/docs/reference/api.md +++ b/site/src/content/docs/reference/api.md @@ -43,3 +43,27 @@ cg.close(); | `buildContext(task, opts)` | Markdown / JSON context for AI | | `watch()` / `unwatch()` | Start / stop the file watcher | | `close()` | Close the database connection | + +CommonJS works too — `const { CodeGraph } = require('@colbymchenry/codegraph');`. + +## Lower-level building blocks + +The same entry point exports primitives for callers that drive the graph directly rather than through the `CodeGraph` facade: `DatabaseConnection`, `QueryBuilder`, `getDatabasePath`, `initGrammars` / `loadGrammarsForLanguages`, and `FileLock`. + +```typescript +import { + CodeGraph, + DatabaseConnection, + QueryBuilder, + getDatabasePath, + initGrammars, + loadGrammarsForLanguages, + FileLock, +} from '@colbymchenry/codegraph'; +``` + +## Embedding requirements + +- **Install from npm** (`npm i @colbymchenry/codegraph`) so the matching per-platform package — which carries the compiled library — is fetched alongside the shim. +- The API runs on **your** runtime, so it needs **Node 22.5+** for the built-in `node:sqlite` module (an Electron main process qualifies when its bundled Node is 22.5+). The CLI and MCP server are unaffected — they ship with a self-contained bundled runtime and need no Node at all. +- TypeScript types ship with the package. Keep `@types/node` available and `skipLibCheck: true` (the common default). diff --git a/site/src/content/docs/reference/cli.md b/site/src/content/docs/reference/cli.md index 76f0e5a..0bf4c1f 100644 --- a/site/src/content/docs/reference/cli.md +++ b/site/src/content/docs/reference/cli.md @@ -7,21 +7,33 @@ description: Every CodeGraph command and the flags it accepts. codegraph # Run interactive installer codegraph install # Run installer (explicit) codegraph uninstall # Remove CodeGraph from your agents (inverse of install) -codegraph init [path] # Initialize in a project (--index to also index) +codegraph init [path] # Initialize a project + build its graph (one step) codegraph uninit [path] # Remove CodeGraph from a project (--force to skip prompt) -codegraph index [path] # Full index (--force to re-index, --quiet for less output) -codegraph sync [path] # Incremental update -codegraph status [path] # Show statistics +codegraph index [path] # Full re-index from scratch (--force, --quiet, --verbose) +codegraph sync [path] # Incremental update (--quiet) +codegraph status [path] # Show statistics (--json) +codegraph unlock [path] # Remove a stale lock file that's blocking indexing codegraph query # Search symbols (--kind, --limit, --json) -codegraph files [path] # Show file structure (--format, --filter, --max-depth, --json) -codegraph context # Build context for AI (--format, --max-nodes) +codegraph explore # Relevant symbols' source + call paths in one shot (same output as the codegraph_explore MCP tool) +codegraph node # One symbol's source + callers, or read a file with line numbers (same output as codegraph_node) +codegraph files [path] # Show file structure (--format, --filter, --pattern, --max-depth, --json) codegraph callers # Find what calls a function/method (--limit, --json) codegraph callees # Find what a function/method calls (--limit, --json) codegraph impact # Analyze what code is affected by changing a symbol (--depth, --json) -codegraph affected [files...] # Find test files affected by changes -codegraph serve --mcp # Start MCP server +codegraph affected [files...] # Find test files affected by changes (see below) +codegraph daemon # Manage background daemons — pick one to stop (alias: daemons) +codegraph telemetry [on|off] # Show or change anonymous usage telemetry +codegraph upgrade [version] # Update to the latest release (--check, --force) +codegraph version # Print the installed version (also -v, --version) +codegraph help [command] # Show help, optionally for one command ``` +The MCP server (`codegraph serve --mcp`) is launched automatically by your agent — you don't run it by hand. See [MCP Server](/codegraph/reference/mcp-server/). + +## init, index, and sync + +`codegraph init` creates the local `.codegraph/` directory **and** builds the full graph in one step. (The old `-i`/`--index` flag is now a no-op, accepted only so existing scripts don't break.) After that the file watcher keeps the graph current automatically — `index` (a full rebuild from scratch) and `sync` (an incremental update) are only needed when the watcher is disabled or you're scripting against the index outside an agent session. + ## Query commands `query`, `callers`, `callees`, and `impact` all accept `--json` for machine-readable output. @@ -32,6 +44,8 @@ codegraph callers handleRequest --json codegraph impact AuthMiddleware --depth 3 ``` +`explore` and `node` are the CLI faces of the `codegraph_explore` and `codegraph_node` MCP tools — same output — so subagents and non-MCP harnesses can reach the graph from a shell. + ## affected Traces import dependencies transitively to find which test files are affected by changed source files. See [Affected Tests in CI](/codegraph/guides/affected-tests/) for options and a CI example. diff --git a/site/src/content/docs/reference/integrations.md b/site/src/content/docs/reference/integrations.md index 2a20cad..1b4b87c 100644 --- a/site/src/content/docs/reference/integrations.md +++ b/site/src/content/docs/reference/integrations.md @@ -3,7 +3,7 @@ title: Integrations description: Supported agents, and manual MCP setup. --- -The interactive installer auto-detects and configures each supported agent — wiring up the MCP server and writing its instructions file. +The interactive installer auto-detects and configures each supported agent — wiring the CodeGraph MCP server into each. For the agents that use an instructions file, it also writes a short marker-fenced CodeGraph section (`CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`) so subagents and non-MCP harnesses learn the `codegraph explore` command; `codegraph uninstall` removes it. ## Supported agents @@ -40,24 +40,20 @@ Add the MCP server to `~/.claude.json`: } ``` -Optionally auto-allow the read-only tools in `~/.claude/settings.json`: +Optionally auto-allow CodeGraph's tools in `~/.claude/settings.json`: ```json { "permissions": { "allow": [ - "mcp__codegraph__codegraph_search", - "mcp__codegraph__codegraph_callers", - "mcp__codegraph__codegraph_callees", - "mcp__codegraph__codegraph_impact", - "mcp__codegraph__codegraph_node", - "mcp__codegraph__codegraph_status", - "mcp__codegraph__codegraph_files" + "mcp__codegraph__*" ] } } ``` +One wildcard auto-approves every CodeGraph tool. The server lists a single tool by default — `codegraph_explore` — but if you re-enable others via the `CODEGRAPH_MCP_TOOLS` environment variable, they're already permitted with no prompt. + :::tip Cursor launches MCP subprocesses with the wrong working directory. The installer handles this for you by injecting a `--path` argument; if you wire Cursor up by hand, pass the project path explicitly. ::: diff --git a/site/src/content/docs/reference/languages.md b/site/src/content/docs/reference/languages.md index 184b579..0c55877 100644 --- a/site/src/content/docs/reference/languages.md +++ b/site/src/content/docs/reference/languages.md @@ -18,13 +18,16 @@ Language support is automatic from the file extension — there's nothing to con | Ruby | `.rb` | Full support | | C | `.c`, `.h` | Full support | | C++ | `.cpp`, `.hpp`, `.cc` | Full support | +| Objective-C | `.m`, `.mm`, `.h` | Partial support (classes, protocols, methods, `@property`, `#import`, message sends; `.mm` ObjC++ may parse incompletely) | | Swift | `.swift` | Full support | | Kotlin | `.kt`, `.kts` | Full support | | Scala | `.scala`, `.sc` | Full support (classes, traits, methods, type aliases, Scala 3 enums) | | Dart | `.dart` | Full support | | Svelte | `.svelte` | Full support (script extraction, Svelte 5 runes, SvelteKit routes) | | Vue | `.vue` | Full support (script + script-setup, Nuxt page/API/middleware routes) | +| Astro | `.astro` | Full support (frontmatter + script extraction, template component/call references, `src/pages/` routes) | | Liquid | `.liquid` | Full support | | Pascal / Delphi | `.pas`, `.dpr`, `.dpk`, `.lpr` | Full support (classes, records, interfaces, enums, DFM/FMX forms) | | Lua | `.lua` | Full support (functions, methods, locals, `require` imports, call edges) | +| R | `.R`, `.r` | Full support (functions, S4/R5/R6 classes with methods, `library`/`require` imports, `source()` file references, call edges) | | Luau | `.luau` | Full support (Lua, plus typed signatures, `type` aliases, Roblox `require`) | diff --git a/site/src/content/docs/reference/mcp-server.md b/site/src/content/docs/reference/mcp-server.md index 63c3e32..c9e4365 100644 --- a/site/src/content/docs/reference/mcp-server.md +++ b/site/src/content/docs/reference/mcp-server.md @@ -3,29 +3,44 @@ title: MCP Server description: The tools CodeGraph exposes to AI agents over MCP. --- -CodeGraph runs as a [Model Context Protocol](https://modelcontextprotocol.io/) server. Start it with: +CodeGraph runs as a [Model Context Protocol](https://modelcontextprotocol.io/) server. Agents configured by the installer launch it automatically — you don't start it by hand: ```bash codegraph serve --mcp ``` -Agents configured by the installer launch this automatically. When a `.codegraph/` index exists, the agent uses the tools below. +When a `.codegraph/` index exists, the agent gets the tool below. In a workspace with **no** index, the server announces itself inactive and lists **no** tools — the agent works normally with its built-in tools, and indexing stays your decision. -## Tools +## One tool by default: `codegraph_explore` + +By default the server exposes a **single tool**, `codegraph_explore`. It's Read-equivalent: give it a natural-language question or a bag of symbol and file names, and it returns the **verbatim, line-numbered source** of the relevant symbols grouped by file — the same shape the `Read` tool gives you — plus the call paths between them (including dynamic-dispatch hops like callbacks, React re-render, and JSX children that grep can't follow) and a blast-radius summary of what depends on them. One call usually answers the whole question. + +Exposing a single strong tool is deliberate. Measured agent behavior showed that one well-aimed tool steers agents to a direct answer better than a menu of narrower ones — fewer mis-picks — and agents reach for it both when answering questions and while editing code. + +## The other tools + +Seven more tools exist and stay fully functional, but are **unlisted by default** — everything they return already arrives inline on a `codegraph_explore` response (its blast-radius section, the relationship map, a symbol's body and its callee list): | Tool | Purpose | |---|---| -| `codegraph_search` | Find symbols by name across the codebase | +| `codegraph_node` | One symbol's source + caller/callee trail, or a whole file read with line numbers (Read-parity). Returns every overload's body for an ambiguous name. | +| `codegraph_search` | Find symbols by name across the codebase (locations only) | | `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_files` | Get the indexed file structure (faster than filesystem scanning) | | `codegraph_status` | Check index health and statistics | +Re-enable any of them with the `CODEGRAPH_MCP_TOOLS` environment variable — a comma-separated allowlist of short names that replaces the default: + +```bash +CODEGRAPH_MCP_TOOLS=explore,node,search,callers +``` + +Each also has a CLI equivalent (`codegraph node` / `query` / `callers` / `callees` / `impact` / `files` / `status`) for scripts and non-MCP harnesses. + ## How agents should use it -CodeGraph *is* the pre-built search index. For "how does X work?", architecture, trace, or where-is-X questions, an agent should answer in a handful of CodeGraph calls and stop — typically with **zero file reads** — rather than re-deriving the answer with `grep` + `Read`. A direct CodeGraph answer is a handful of calls; a grep/read exploration is dozens. +CodeGraph *is* the pre-built search index. For "how does X work?", architecture, a flow ("how does X reach Y"), or where-is-X questions — and while editing code — an agent should answer with `codegraph_explore` and stop, typically with **zero file reads**, rather than re-deriving the answer with `grep` + `Read`. A direct CodeGraph answer is one to a few calls; a grep/read exploration is dozens. -The installer writes this guidance into each agent's instructions file automatically. +The MCP server delivers this guidance to the main agent automatically, in the MCP `initialize` response. Because subagents and non-MCP harnesses never see that response, the installer also writes a short marker-fenced section into each agent's instructions file pointing at the `codegraph explore` CLI equivalent. diff --git a/site/src/content/docs/troubleshooting.md b/site/src/content/docs/troubleshooting.md index 2a4de29..2699942 100644 --- a/site/src/content/docs/troubleshooting.md +++ b/site/src/content/docs/troubleshooting.md @@ -20,8 +20,12 @@ Current builds shouldn't: CodeGraph bundles its own Node runtime and uses Node's ## MCP server not connecting -Ensure the project is initialized/indexed, verify the path in your MCP config, and check that `codegraph serve --mcp` works from the command line. +Your agent starts the server itself, so you don't launch it by hand. Make sure the project is initialized and indexed (`codegraph status`) and that the path in your MCP config is correct. If it still won't connect, re-run `codegraph install` to rewrite the config. ## Missing symbols -The MCP server auto-syncs on save (wait a couple of seconds). Run `codegraph sync` manually if needed. Check that the file's language is [supported](/codegraph/reference/languages/) and isn't excluded by `.gitignore`. +The MCP server auto-syncs on save (wait a couple of seconds). Run `codegraph sync` manually if needed. Check that the file's language is [supported](/codegraph/reference/languages/) and isn't inside a `.gitignore`d or default-excluded directory (e.g. `node_modules`, `dist`). + +## Sharing one checkout between Windows and WSL + +Don't point both at the same `.codegraph/`: the background-server lock and the SQLite index are tied to the OS that wrote them, and SQLite locking across the WSL2/Windows filesystem boundary is unreliable. Give each side its own index in the same tree by setting `CODEGRAPH_DIR` to a distinct name on one of them — e.g. `CODEGRAPH_DIR=.codegraph-win` on Windows, leaving WSL on the default `.codegraph`. CodeGraph skips any sibling `.codegraph-*` directory when indexing and watching, so the two never trip over each other.