docs: reframe value prop around precision/speed, update Node floor to 20, and expand language/framework coverage
- 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
This commit is contained in:
Colby McHenry
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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> # 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 explore <query> # Relevant symbols' source + call paths in one shot (same output as the codegraph_explore MCP tool)
|
||||
codegraph node <symbol|file> # 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 <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)
|
||||
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.
|
||||
|
||||
@@ -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.
|
||||
:::
|
||||
|
||||
@@ -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`) |
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user