Add landing page + Starlight docs site (#375)
* udpated matrix * feat(site): add landing page + Starlight docs site Astro + Starlight site in site/ — a flat/paper editorial landing page plus 18 docs pages seeded from the README. Monochrome theme, hairline rules, square corners, live GitHub star count, light default + dark toggle. Deploys to GitHub Pages via .github/workflows/deploy-site.yml. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Colby Mchenry
co-authored by
Claude Opus 4.7
Claude Opus 4.7
parent
1f3625a3e9
commit
4509b45dd5
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: How It Works
|
||||
description: The extraction, storage, resolution, and auto-sync pipeline.
|
||||
---
|
||||
|
||||
CodeGraph turns source code into a queryable graph in four stages.
|
||||
|
||||
```
|
||||
files → Extraction (tree-sitter) → DB (nodes/edges/files)
|
||||
↓
|
||||
Resolution (imports, name-matching, framework patterns)
|
||||
↓
|
||||
Graph queries (callers, callees, impact)
|
||||
↓
|
||||
Context building (markdown / JSON for AI consumption)
|
||||
```
|
||||
|
||||
## 1. Extraction
|
||||
|
||||
[tree-sitter](https://tree-sitter.github.io/) parses source into ASTs. Language-specific queries extract **nodes** (functions, classes, methods, types…) and **edges** (calls, imports, extends, implements). Heavy parsing runs off the main thread.
|
||||
|
||||
## 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.
|
||||
|
||||
## 3. Resolution
|
||||
|
||||
After extraction, references are resolved: function calls → definitions, imports → source files, class inheritance, and framework-specific patterns. Some dynamic-dispatch boundaries (callbacks, observers, React re-render, JSX children) are bridged by synthesizers so flows connect end-to-end. See [Resolution & Frameworks](/codegraph/core-concepts/resolution/).
|
||||
|
||||
## 4. Auto-sync
|
||||
|
||||
The MCP server watches your project using native OS file events (FSEvents / inotify / ReadDirectoryChangesW). Changes are debounced, filtered to source files, and incrementally synced — the graph stays fresh as you code, with no configuration.
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: The Knowledge Graph
|
||||
description: The node and edge kinds the graph is built from.
|
||||
---
|
||||
|
||||
CodeGraph stores three things: **nodes** (symbols and files), **edges** (relationships between them), and **files**. Every node and edge carries an exact `kind`, drawn from a fixed vocabulary so queries are consistent across languages.
|
||||
|
||||
## Node kinds
|
||||
|
||||
`file`, `module`, `class`, `struct`, `interface`, `trait`, `protocol`, `function`, `method`, `property`, `field`, `variable`, `constant`, `enum`, `enum_member`, `type_alias`, `namespace`, `parameter`, `import`, `export`, `route`, `component`.
|
||||
|
||||
## Edge kinds
|
||||
|
||||
`contains`, `calls`, `imports`, `exports`, `extends`, `implements`, `references`, `type_of`, `returns`, `instantiates`, `overrides`, `decorates`.
|
||||
|
||||
## Provenance
|
||||
|
||||
Most edges come straight from the AST. A few — at dynamic-dispatch boundaries that static parsing can't follow — are **synthesized** and marked with `provenance: 'heuristic'` plus the wiring site that created them. These are surfaced inline in `trace`, the `node` trail, and `context` call-paths, so an agent can see exactly where a connection came from.
|
||||
|
||||
## Querying it
|
||||
|
||||
- **Search** symbols by name (FTS5).
|
||||
- **Callers / callees** walk the call graph one hop at a time.
|
||||
- **Impact** computes the transitive radius affected by a change.
|
||||
- **Trace** returns a whole call path between two symbols in one call.
|
||||
|
||||
See the [CLI](/codegraph/reference/cli/) and [MCP Server](/codegraph/reference/mcp-server/) references for how to run these.
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Resolution & Frameworks
|
||||
description: How CodeGraph connects references and links routes to handlers.
|
||||
---
|
||||
|
||||
Extraction produces nodes and raw edges; **resolution** turns names into real connections.
|
||||
|
||||
## Reference resolution
|
||||
|
||||
After parsing, CodeGraph resolves:
|
||||
|
||||
- **Imports** → the source files they point at (including tsconfig path aliases and cargo workspace members).
|
||||
- **Calls** → their definitions, by import resolution and name matching.
|
||||
- **Inheritance** → `extends` / `implements` between types.
|
||||
|
||||
## Framework awareness
|
||||
|
||||
CodeGraph recognizes web-framework routing files and emits `route` nodes linked by `references` edges to their handler classes or functions — so querying the callers of a view or controller surfaces the URL pattern that binds it. See [Framework Routes](/codegraph/guides/framework-routes/) for the full list of recognized frameworks.
|
||||
|
||||
## Dynamic-dispatch coverage
|
||||
|
||||
Static parsing misses computed and indirect calls, so flows can break at dynamic dispatch. CodeGraph bridges several of these boundaries with synthesizers so a flow connects end-to-end:
|
||||
|
||||
- Callback / observer registration
|
||||
- `EventEmitter` channels
|
||||
- React re-render (`setState` → `render`)
|
||||
- JSX child (`render` → child component)
|
||||
- Django ORM descriptors
|
||||
|
||||
Every synthesized edge is marked `provenance: 'heuristic'` with the site that wired it, and is shown inline wherever a path crosses it.
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: Configuration
|
||||
description: CodeGraph is zero-config — here's what that means in practice.
|
||||
---
|
||||
|
||||
There isn't any — CodeGraph is **zero-config**. It indexes every file whose extension maps to a [supported language](/codegraph/reference/languages/) and **respects your `.gitignore`**: in git repos via git itself, and in non-git projects by reading `.gitignore` files directly (root and nested, the same way git would).
|
||||
|
||||
## What that means in practice
|
||||
|
||||
- Anything git ignores — `node_modules`, build output, secrets in `.env` — is never indexed. **To keep something out of the graph, add it to `.gitignore`.**
|
||||
- There's no config file to write or keep in sync, and nothing to wire up per language: support is automatic from the file extension.
|
||||
- Files larger than 1 MB are skipped (generated bundles, minified JS, vendored blobs) — they cost parse budget for no useful symbols.
|
||||
|
||||
:::note
|
||||
Committed files that aren't gitignored *are* indexed, even under `vendor/` or a committed `dist/`. If you commit a dependency or build directory you don't want in the graph, add it to `.gitignore`.
|
||||
:::
|
||||
|
||||
## Where data lives
|
||||
|
||||
Per-project data lives in a `.codegraph/` directory at your project root, containing the SQLite database (`codegraph.db`). Nothing leaves your machine.
|
||||
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: Installation
|
||||
description: Install CodeGraph and configure your AI coding agents.
|
||||
---
|
||||
|
||||
## 1. Run the installer
|
||||
|
||||
```bash
|
||||
npx @colbymchenry/codegraph
|
||||
```
|
||||
|
||||
The installer will:
|
||||
|
||||
- Ask which agent(s) to configure — auto-detecting installed ones from **Claude Code**, **Cursor**, **Codex CLI**, **opencode**, and **Hermes Agent**.
|
||||
- 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`).
|
||||
- Set up auto-allow permissions when Claude Code is one of the targets.
|
||||
- Initialize your current project (local installs only).
|
||||
|
||||
## Non-interactive (scripting / CI)
|
||||
|
||||
```bash
|
||||
codegraph install --yes # auto-detect agents, install global
|
||||
codegraph install --target=cursor,claude --yes # explicit target list
|
||||
codegraph install --target=auto --location=local # detected agents, project-local
|
||||
codegraph install --print-config codex # print snippet, no file writes
|
||||
```
|
||||
|
||||
| Flag | Values | Default |
|
||||
|---|---|---|
|
||||
| `--target` | `auto`, `all`, `none`, or csv (`claude,cursor,…`) | prompt |
|
||||
| `--location` | `global`, `local` | prompt |
|
||||
| `--yes` | (boolean) | prompt every step |
|
||||
| `--no-permissions` | (boolean) skip Claude auto-allow list | permissions on |
|
||||
| `--print-config <id>` | dump snippet for one agent and exit | — |
|
||||
|
||||
## 2. Restart your agent
|
||||
|
||||
Restart your agent (Claude Code / Cursor / Codex CLI / opencode / Hermes Agent) for the MCP server to load.
|
||||
|
||||
## 3. Initialize projects
|
||||
|
||||
```bash
|
||||
cd your-project
|
||||
codegraph init -i
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Supported platforms
|
||||
|
||||
Every release ships a self-contained build (bundled Node runtime — nothing to compile) for all three desktop OSes, on both x64 and arm64:
|
||||
|
||||
| Platform | Architectures | Install |
|
||||
|---|---|---|
|
||||
| Windows | x64, arm64 | PowerShell installer or npm |
|
||||
| macOS | x64, arm64 | shell installer or npm |
|
||||
| Linux | x64, arm64 | shell installer or npm |
|
||||
|
||||
## Uninstall
|
||||
|
||||
Changed your mind? One command removes CodeGraph from every agent it configured:
|
||||
|
||||
```bash
|
||||
codegraph uninstall
|
||||
```
|
||||
|
||||
This reverses the installer — stripping CodeGraph's MCP server config, instructions, and permissions from each configured agent. Your project indexes (`.codegraph/`) are left untouched; remove those per-project with `codegraph uninit`. Use `--target` to remove from specific agents, or `--yes` to run non-interactively.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Introduction
|
||||
description: What CodeGraph is, and why it makes AI coding agents faster and cheaper.
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
It exists to make AI coding agents — Claude Code, Cursor, Codex CLI, opencode, and Hermes Agent — **answer structural questions without scanning files**. Instead of fanning out across `grep`, `glob`, and `Read` to reconstruct how code fits together, an agent queries a pre-built index and gets the answer in a handful of calls.
|
||||
|
||||
## 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.
|
||||
|
||||
Tested across 7 real-world open-source codebases (median of 4 runs per arm), giving an agent CodeGraph was on average:
|
||||
|
||||
- **35% cheaper**
|
||||
- **57% fewer tokens**
|
||||
- **46% faster**
|
||||
- **71% fewer tool calls**
|
||||
|
||||
The gains scale with codebase size — on large repos the agent answers from the index with **zero file reads**.
|
||||
|
||||
## What's in the graph
|
||||
|
||||
- **Symbols** — functions, classes, methods, types, routes, components, and more.
|
||||
- **Edges** — calls, imports, inheritance, references, and framework-specific relationships.
|
||||
- **Files** — structure plus full-text search (FTS5).
|
||||
|
||||
Extraction is **deterministic** — derived from the AST, never LLM-summarized.
|
||||
|
||||
## 100% local
|
||||
|
||||
No data leaves your machine. No API keys, no external services — just a SQLite database in `.codegraph/`.
|
||||
|
||||
Ready to try it? Head to the [Quickstart](/codegraph/getting-started/quickstart/).
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: Next Steps
|
||||
description: Where to go once CodeGraph is installed and indexing.
|
||||
---
|
||||
|
||||
You've got CodeGraph installed and a graph built. Here's where to go next.
|
||||
|
||||
## Understand the model
|
||||
|
||||
- [How It Works](/codegraph/core-concepts/how-it-works/) — the extraction → storage → resolution → sync pipeline.
|
||||
- [The Knowledge Graph](/codegraph/core-concepts/knowledge-graph/) — the node and edge kinds the graph is built from.
|
||||
- [Resolution & Frameworks](/codegraph/core-concepts/resolution/) — how references and framework routes get connected.
|
||||
|
||||
## Put it to work
|
||||
|
||||
- [Indexing a Project](/codegraph/guides/indexing/) — full index, incremental sync, and the file watcher.
|
||||
- [Framework Routes](/codegraph/guides/framework-routes/) — link URL patterns to their handlers.
|
||||
- [Affected Tests in CI](/codegraph/guides/affected-tests/) — run only the tests a change touches.
|
||||
|
||||
## Reference
|
||||
|
||||
- [MCP Server](/codegraph/reference/mcp-server/) — the tools agents call.
|
||||
- [CLI](/codegraph/reference/cli/) — every command and flag.
|
||||
- [API](/codegraph/reference/api/) — use CodeGraph as a TypeScript library.
|
||||
- [Integrations](/codegraph/reference/integrations/) — supported agents and manual setup.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
title: Get Started
|
||||
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
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
|
||||
|
||||
# Windows (PowerShell)
|
||||
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
|
||||
```
|
||||
|
||||
## Already have Node? Use npm instead (works on any version)
|
||||
|
||||
```bash
|
||||
npx @colbymchenry/codegraph # zero-install, or:
|
||||
npm i -g @colbymchenry/codegraph
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Initialize Projects
|
||||
|
||||
```bash
|
||||
cd your-project
|
||||
codegraph init -i
|
||||
```
|
||||
|
||||
That's it — 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.
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
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.
|
||||
|
||||
## Index a project
|
||||
|
||||
```bash
|
||||
cd your-project
|
||||
codegraph init -i # initialize + index in one step
|
||||
```
|
||||
|
||||
`init` creates the `.codegraph/` directory; `-i` (or `--index`) immediately builds the full index. For an existing project you can re-index any time:
|
||||
|
||||
```bash
|
||||
codegraph index # full index
|
||||
codegraph sync # incremental update of changed files
|
||||
```
|
||||
|
||||
## Check it worked
|
||||
|
||||
```bash
|
||||
codegraph status
|
||||
```
|
||||
|
||||
This reports the node/edge/file counts, the active SQLite backend, and the journal mode — a quick health check that the index is ready.
|
||||
|
||||
## Run a query
|
||||
|
||||
```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/).
|
||||
|
||||
## Hand it to your agent
|
||||
|
||||
With a `.codegraph/` directory present and an agent configured (see [Installation](/codegraph/getting-started/installation/)), your agent uses the [MCP tools](/codegraph/reference/mcp-server/) automatically — no extra step.
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: Affected Tests in CI
|
||||
description: Run only the tests a change actually touches.
|
||||
---
|
||||
|
||||
`codegraph affected` traces import dependencies transitively to find which test files are affected by a set of changed source files — so CI can run only the relevant tests.
|
||||
|
||||
```bash
|
||||
codegraph affected src/utils.ts src/api.ts # pass files as arguments
|
||||
git diff --name-only | codegraph affected --stdin # pipe from git diff
|
||||
codegraph affected src/auth.ts --filter "e2e/*" # custom test-file pattern
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Description | Default |
|
||||
|---|---|---|
|
||||
| `--stdin` | Read the file list from stdin | `false` |
|
||||
| `-d, --depth <n>` | Max dependency traversal depth | `5` |
|
||||
| `-f, --filter <glob>` | Custom glob to identify test files | auto-detect |
|
||||
| `-j, --json` | Output as JSON | `false` |
|
||||
| `-q, --quiet` | Output file paths only | `false` |
|
||||
|
||||
## CI / hook example
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
|
||||
if [ -n "$AFFECTED" ]; then
|
||||
npx vitest run $AFFECTED
|
||||
fi
|
||||
```
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: Framework Routes
|
||||
description: CodeGraph links URL patterns to the handlers that serve them.
|
||||
---
|
||||
|
||||
CodeGraph detects web-framework routing files and emits `route` nodes linked by `references` edges to their handler classes or functions. Querying the callers of a view or controller then surfaces the URL pattern that binds it.
|
||||
|
||||
| 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 |
|
||||
| **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 |
|
||||
| **Spring** | `@GetMapping`, `@PostMapping`, `@RequestMapping` on methods |
|
||||
| **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 |
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: Indexing a Project
|
||||
description: Full index, incremental sync, and the file watcher.
|
||||
---
|
||||
|
||||
## Initialize and index
|
||||
|
||||
```bash
|
||||
cd your-project
|
||||
codegraph init -i # initialize + full index
|
||||
```
|
||||
|
||||
`init` creates `.codegraph/`; `-i`/`--index` builds the index immediately. To initialize without indexing, drop the flag and run `codegraph index` later.
|
||||
|
||||
## Full vs. incremental
|
||||
|
||||
```bash
|
||||
codegraph index # full index of the whole project
|
||||
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.
|
||||
|
||||
## Stay fresh automatically
|
||||
|
||||
When the MCP server is running, CodeGraph watches your project with native OS file events and syncs in the background — debounced, and filtered to source files only. You don't need to run `sync` by hand during an agent session.
|
||||
|
||||
## Check status
|
||||
|
||||
```bash
|
||||
codegraph status
|
||||
```
|
||||
|
||||
Reports node/edge/file counts, the active SQLite backend, and the journal mode.
|
||||
|
||||
## What gets indexed
|
||||
|
||||
Every file whose extension maps to a [supported language](/codegraph/reference/languages/), minus anything your `.gitignore` excludes and files over 1 MB. See [Configuration](/codegraph/getting-started/configuration/).
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: API
|
||||
description: Use CodeGraph as a TypeScript library.
|
||||
---
|
||||
|
||||
CodeGraph ships a TypeScript API. The public surface is the `CodeGraph` class.
|
||||
|
||||
```typescript
|
||||
import CodeGraph from '@colbymchenry/codegraph';
|
||||
|
||||
const cg = await CodeGraph.init('/path/to/project');
|
||||
// Or open an existing index:
|
||||
// const cg = await CodeGraph.open('/path/to/project');
|
||||
|
||||
await cg.indexAll({
|
||||
onProgress: (p) => console.log(`${p.phase}: ${p.current}/${p.total}`),
|
||||
});
|
||||
|
||||
const results = cg.searchNodes('UserService');
|
||||
const callers = cg.getCallers(results[0].node.id);
|
||||
const context = await cg.buildContext('fix login bug', {
|
||||
maxNodes: 20,
|
||||
includeCode: true,
|
||||
format: 'markdown',
|
||||
});
|
||||
const impact = cg.getImpactRadius(results[0].node.id, 2);
|
||||
|
||||
cg.watch(); // auto-sync on file changes
|
||||
cg.unwatch(); // stop watching
|
||||
cg.close();
|
||||
```
|
||||
|
||||
## Key methods
|
||||
|
||||
| Method | Purpose |
|
||||
|---|---|
|
||||
| `CodeGraph.init(path)` / `CodeGraph.open(path)` | Create or open a project index |
|
||||
| `indexAll(opts)` | Full index, with progress callback |
|
||||
| `sync()` | Incremental update |
|
||||
| `searchNodes(query)` | Full-text symbol search |
|
||||
| `getCallers(id)` / `getCallees(id)` | Walk the call graph |
|
||||
| `getImpactRadius(id, depth)` | Transitive impact of a change |
|
||||
| `buildContext(task, opts)` | Markdown / JSON context for AI |
|
||||
| `watch()` / `unwatch()` | Start / stop the file watcher |
|
||||
| `close()` | Close the database connection |
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: CLI
|
||||
description: Every CodeGraph command and the flags it accepts.
|
||||
---
|
||||
|
||||
```bash
|
||||
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 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 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)
|
||||
codegraph affected [files...] # Find test files affected by changes
|
||||
codegraph serve --mcp # Start MCP server
|
||||
```
|
||||
|
||||
## Query commands
|
||||
|
||||
`query`, `callers`, `callees`, and `impact` all accept `--json` for machine-readable output.
|
||||
|
||||
```bash
|
||||
codegraph query UserService --kind class --limit 10
|
||||
codegraph callers handleRequest --json
|
||||
codegraph impact AuthMiddleware --depth 3
|
||||
```
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,61 @@
|
||||
---
|
||||
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.
|
||||
|
||||
## Supported agents
|
||||
|
||||
- **Claude Code**
|
||||
- **Cursor**
|
||||
- **Codex CLI**
|
||||
- **opencode**
|
||||
- **Hermes Agent**
|
||||
|
||||
Run `npx @colbymchenry/codegraph` and pick your agent(s); see [Installation](/codegraph/getting-started/installation/) for the non-interactive flags.
|
||||
|
||||
## Manual setup
|
||||
|
||||
If you'd rather wire it up yourself, install globally:
|
||||
|
||||
```bash
|
||||
npm install -g @colbymchenry/codegraph
|
||||
```
|
||||
|
||||
Add the MCP server to `~/.claude.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"codegraph": {
|
||||
"type": "stdio",
|
||||
"command": "codegraph",
|
||||
"args": ["serve", "--mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Optionally auto-allow the read-only tools in `~/.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"mcp__codegraph__codegraph_search",
|
||||
"mcp__codegraph__codegraph_context",
|
||||
"mcp__codegraph__codegraph_callers",
|
||||
"mcp__codegraph__codegraph_callees",
|
||||
"mcp__codegraph__codegraph_impact",
|
||||
"mcp__codegraph__codegraph_node",
|
||||
"mcp__codegraph__codegraph_status",
|
||||
"mcp__codegraph__codegraph_files"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
:::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.
|
||||
:::
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: Languages
|
||||
description: Every language CodeGraph parses, and the extensions it recognizes.
|
||||
---
|
||||
|
||||
Language support is automatic from the file extension — there's nothing to configure.
|
||||
|
||||
| Language | Extensions | Status |
|
||||
|---|---|---|
|
||||
| TypeScript | `.ts`, `.tsx` | Full support |
|
||||
| JavaScript | `.js`, `.jsx`, `.mjs` | Full support |
|
||||
| Python | `.py` | Full support |
|
||||
| Go | `.go` | Full support |
|
||||
| Rust | `.rs` | Full support |
|
||||
| Java | `.java` | Full support |
|
||||
| C# | `.cs` | Full support |
|
||||
| PHP | `.php` | Full support |
|
||||
| Ruby | `.rb` | Full support |
|
||||
| C | `.c`, `.h` | Full support |
|
||||
| C++ | `.cpp`, `.hpp`, `.cc` | Full support |
|
||||
| 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) |
|
||||
| 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) |
|
||||
| Luau | `.luau` | Full support (Lua, plus typed signatures, `type` aliases, Roblox `require`) |
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
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:
|
||||
|
||||
```bash
|
||||
codegraph serve --mcp
|
||||
```
|
||||
|
||||
Agents configured by the installer launch this automatically. When a `.codegraph/` index exists, the agent uses the tools below.
|
||||
|
||||
## Tools
|
||||
|
||||
| Tool | Purpose |
|
||||
|---|---|
|
||||
| `codegraph_search` | Find symbols by name across the codebase |
|
||||
| `codegraph_context` | Build relevant code context for a task — composes search + node + callers + callees in one call |
|
||||
| `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_files` | Get the indexed file structure (faster than filesystem scanning) |
|
||||
| `codegraph_status` | Check index health and statistics |
|
||||
|
||||
## 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.
|
||||
|
||||
The installer writes this guidance into each agent's instructions file automatically.
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: Troubleshooting
|
||||
description: Fixes for the most common CodeGraph issues.
|
||||
---
|
||||
|
||||
## "CodeGraph not initialized"
|
||||
|
||||
Run `codegraph init` in your project directory first.
|
||||
|
||||
## Indexing is slow
|
||||
|
||||
Check that `node_modules` and other large directories are excluded (they are, if gitignored). Use `--quiet` to reduce output overhead.
|
||||
|
||||
## MCP hits `database is locked`
|
||||
|
||||
Current builds shouldn't: CodeGraph bundles its own Node runtime and uses Node's built-in `node:sqlite` in WAL mode, where concurrent reads never block on a writer. If you still see it:
|
||||
|
||||
- **You're on an old (pre-0.9) install.** Reinstall to get the bundled runtime — `curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh` (macOS/Linux), `irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex` (Windows), or `npm i -g @colbymchenry/codegraph@latest`.
|
||||
- **`codegraph status` shows `Journal:` other than `wal`** — WAL couldn't be enabled on this filesystem (common on network shares and WSL2 `/mnt`), so reads can block on writes. Move the project (with its `.codegraph/` folder) onto a local disk.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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`.
|
||||
Reference in New Issue
Block a user