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
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user