codegraph-rust

# CodeGraph-Rust [](https://github.com/sunerpy/codegraph-rust/actions/workflows/ci.yml) [](#license) > A deterministic **code knowledge graph**: tree-sitter parsing persisted to > SQLite/FTS5, exposing traversable symbol / call / dependency relationships to > AI coding agents and developers. > 中文说明 / Chinese: [`docs/readme/README.zh-CN.md`](docs/readme/README.zh-CN.md) CodeGraph(-rust) reads a codebase, extracts symbols and their relationships with tree-sitter, persists them to a per-project SQLite database (with an FTS5 search index), and exposes the result through a CLI and an MCP (Model Context Protocol) stdio server. --- ## Design Highlights - **Deterministic, no AI.** No vector search, no embeddings, no LLM inference. Given the same input the output is byte-stable. Search is FTS5 full-text + multi-signal scoring, not semantic retrieval. This is a hard constraint (enforced by `scripts/guardrail.sh`: `surrealdb`/`rig`/`qdrant`/`lancedb`/ `candle`/`onnx`/`ort` are forbidden). - **Golden byte-stable output.** Node IDs, content hashes, the SQLite `.schema`, FTS5 triggers, and resolved edge sets are all verified against fixed golden artifacts (`reference/golden/`). - **3-tier equivalence oracle.** Tier-1 byte-level (nodes / content hash / schema), Tier-2 multiset (edges / unresolved refs, ignoring row order and autoincrement IDs), Tier-3 only allows presentation-layer diffs explicitly registered in `KNOWN_DIFFS.md`. See [`docs/equivalence.md`](docs/equivalence.md). - **Node-id formula.** Non-file nodes: `{kind}:{sha256("{filePath}:{kind}:{name}:{line}").hex[:32]}`; file nodes are the literal `file:{relpath}` (the tree-sitter file-node special case, no hash). - **Single static binary.** The one `codegraph` executable carries every capability with no Node runtime; SQLite is compiled in via `rusqlite`'s `bundled` feature (FTS5 included). - **Broad language coverage.** ~28 `LANGUAGES` entries: regular tree-sitter grammar languages, embedded languages (Vue / Svelte / Astro / Razor / Liquid / MyBatis XML), a custom DFM extractor, plus R. --- ## Feature Highlights - tree-sitter walker extracting nodes / edges / unresolved refs. - SQLite + FTS5 persistence with a fixed, byte-stable schema. - Cross-file symbol resolution (import resolver + name matcher); concrete React / Vue / NestJS `FrameworkResolver`s are implemented, the rest is an extension point. - Graph traversal: callers / callees / impact (blast radius), type hierarchy, call graph, path finding, and **circular-dependency detection**. - Full-text search: FTS5 + a `searchNodes` multi-signal scoring pipeline. - **Whole-graph export**: dump the entire code graph as NetworkX node-link JSON, with optional deterministic **centrality (PageRank / god-node)** scores. - MCP stdio server exposing **10 tools** (8 core tools + the additive `codegraph_check` cycle detection and `codegraph_export` graph dump). - Per-project single-instance daemon + debounced file watcher + incremental sync. - Built-in benchmark framework (codegraph-bench) for cross-implementation performance comparison. --- ## Workspace Layout (10 crates) | Crate | Responsibility | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `codegraph-core` | Domain types (`Node`/`Edge`/`Language`/`NodeKind`/`EdgeKind`), node-id & content hashing, config, logging. | | `codegraph-store` | SQLite + FTS5 persistence with a fixed, byte-stable `.schema`. | | `codegraph-extract` | tree-sitter engine: walker, per-language specs, embedded & custom (DFM/MyBatis) extractors. | | `codegraph-graph` | Graph traversal (callers/callees/impact/type-hierarchy/paths/cycle detection) + FTS5 scoring + whole-graph export / centrality. | | `codegraph-resolve` | import resolver + name matcher + React/Vue/NestJS `FrameworkResolver`s. | | `codegraph-mcp` | MCP stdio JSON-RPC server and handlers for 10 tools. | | `codegraph-cli` | The `codegraph` single binary (17 subcommands). | | `codegraph-daemon` | Per-project single-instance daemon (pid + socket file, ppid watchdog). | | `codegraph-watch` | Debounced file watcher + incremental sync (content-hash gated). | | `codegraph-bench` | Benchmark + equivalence-oracle library + `bench` binary. | Dependency graph and per-layer detail in [`docs/architecture.md`](docs/architecture.md). --- ## Installation The CLI package is **`codegraph-rs`** and installs a single binary named **`codegraph`**. SQLite is compiled in via `rusqlite`'s `bundled` feature (no system SQLite needed; FTS5 included). Install a prebuilt binary, or build from the repo — it is not published to crates.io. <details> <summary><b>🤖 For AI agents / LLMs — read this first</b></summary> You are an AI coding agent. CodeGraph is a deterministic code knowledge graph (tree-sitter + SQLite/FTS5) that answers structural questions about a codebase — "who calls X", "what does changing X break", "where is X", "how does this area work" — in **one sub-millisecond query instead of dozens of grep + file reads**. It returns verbatim source plus the caller/callee/impact graph, so you get more accurate context in far fewer tokens and round-trips. No AI/LLM inside it — it is pure pre-computed structure for _you_ to consume. **Install + index a project:** ```bash cargo install --git https://github.com/sunerpy/codegraph-rust codegraph-rs # binary: `codegraph` codegraph init /path/to/project # create the index DB (.codegraph/) codegraph index /path/to/project # parse + build the graph ``` **Use it as an MCP server (recommended for agents).** It speaks MCP over stdio: ```bash codegraph serve --mcp --path /path/to/project ``` Auto-register it into your agent's config (Claude Code, Cursor, Codex CLI, opencode, Hermes, Gemini CLI, Antigravity, Kiro): ```bash codegraph install --yes # detects installed agents and wires them up ``` **MCP tools you can call** (prefer these over grep/read for indexed source): | tool | use it for | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `codegraph_explore` | PRIMARY — "how does X work", architecture, a flow, surveying an area. One call returns the relevant symbols' source grouped by file. | | `codegraph_search` | locate a symbol by name (kind + file:line + signature) | | `codegraph_node` | read a symbol/file's verbatim source + its caller/callee trail (a smarter `Read`) | | `codegraph_callers` / `codegraph_callees` | who calls this / what this calls | | `codegraph_impact` | blast radius of changing a symbol (transitive) | | `codegraph_files` / `codegraph_status` | list a directory / check index readiness | **Rules of thumb:** reach for `codegraph_explore` _before_ reading files; trust its results (full AST parse — don't re-verify with grep); use `codegraph_impact` for refactor blast-radius rather than walking callers by hand. The index lags file writes by ~1s; tool responses flag any stale files. </details> ### With cargo (from git) ```bash cargo install --git https://github.com/sunerpy/codegraph-rust codegraph-rs codegraph --version ``` ### Prebuilt binaries Download a prebuilt archive for your platform from the [Releases](https://github.com/sunerpy/codegraph-rust/releases) page, extract it, and put the `codegraph` binary on your `PATH`. Assets are named `codegraph-<version>-<target>.<ext>`: | Platform | Arch | Asset target | | -------- | ----------------------- | ---------------------------- | | Linux | x86_64 (static, musl) | `x86_64-unknown-linux-musl` | | Linux | aarch64 (static, musl) | `aarch64-unknown-linux-musl` | | macOS | x86_64 | `x86_64-apple-darwin` | | macOS | aarch64 (Apple Silicon) | `aarch64-apple-darwin` | The Linux builds are statically linked against musl, so they run on any distribution with no glibc/SQLite system dependency. Prebuilt binaries target Linux and macOS only; the per-project daemon is Unix-socket based, so Windows is not a prebuilt target yet — on Windows, build from source with `cargo install --git https://github.com/sunerpy/codegraph-rust codegraph-rs` (the CLI and MCP server work; the background daemon does not). ### From source Prerequisite: Rust stable (MSRV 1.70). ```bash git clone https://github.com/sunerpy/codegraph-rust.git cd codegraph-rust make release # optimized build -> dist/codegraph make install # cargo install --path crates/codegraph-cli # or directly: cargo install --path crates/codegraph-cli ``` Common developer tasks are wrapped in the `Makefile` — run `make help` to list them (`make ci` runs fmt-check + clippy + test + the scope guardrail). --- ## Quickstart The commands below run against `crates/codegraph-bench/fixtures/mini/` (a 3-file deterministic sample). The index database is written to `<project>/.codegraph/codegraph.db`. ```bash cp -r crates/codegraph-bench/fixtures/mini /tmp/cg-demo codegraph init /tmp/cg-demo # init also runs the first index codegraph query Counter -p /tmp/cg-demo -l 3 # full-text search (-p/--path) codegraph status /tmp/cg-demo # index stats (path is positional) codegraph files -p /tmp/cg-demo # list indexed files codegraph callers add -p /tmp/cg-demo # who calls a symbol codegraph callees runDemo -p /tmp/cg-demo # what a symbol calls codegraph impact add -p /tmp/cg-demo -d 2 # blast radius of a change codegraph check --path /tmp/cg-demo # circular-dependency detection codegraph export --path /tmp/cg-demo --out graph.json # whole-graph JSON codegraph query Counter -p /tmp/cg-demo -l 1 -j # JSON output ``` > Path convention: `init`/`uninit`/`index`/`sync`/`status`/`callers`/`callees`/ > `impact`/`affected`/`unlock`/`check`/`export` take the project path as a > **positional** argument (or `-p/--path`); `query`/`files`/`serve` use `-p/--path`. --- ## CLI Subcommands (17) | Subcommand | Purpose | Key flags | | ----------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | `install` | Write the codegraph MCP server into each AI agent's config | `-t/--target`, `-l/--location`, `--global`, `--local`, `-y/--yes`, `--no-permissions`, `--print-config <id>` | | `uninstall` | Remove codegraph from agent configs (inverse of `install`) | `-t/--target`, `-l/--location`, `--global`, `--local`, `-y/--yes` | | `init` | Initialize `.codegraph/` and run the first full index | `[path]` | | `uninit` | Delete the project's `.codegraph/` index | `[path]`, `-f/--force` | | `index` | (Re-)index in full | `[path]`, `-f/--force`, `-q/--quiet`, `-v/--verbose` | | `sync` | Sync changes (currently reuses the safe full-index path) | `[path]`, `-q/--quiet` | | `status` | Print index stats (files/nodes/edges/DB size/journal) | `[path]`, `-j/--json` | | `query` | FTS5 + multi-signal scored search | `<search>`, `-p`, `-l/--limit`, `-k/--kind`, `-j` | | `files` | List indexed files (tree/flat/grouped) | `-p`, `--filter`, `--pattern`, `--format`, `--max-depth`, `-j` | | `serve` | Start the server; `--mcp` enters MCP stdio mode | `-p`, `--mcp`, `--no-watch` | | `unlock` | Clear a stale daemon lock (keeps live pids) | `[path]` | | `callers` | Who calls a symbol (along calls/references/imports) | `<symbol>`, `-p`, `-l`, `-j` | | `callees` | What a symbol calls | `<symbol>`, `-p`, `-l`, `-j` | | `impact` | Blast radius of changing a symbol (incoming deps) | `<symbol>`, `-p`, `-d/--depth`, `-j` | | `affected` | Given changed files, the affected symbol set | `[files...]`, `-p`, `-d/--depth`, `--filter` | | `check` | Detect circular dependencies (each cycle as `a.ts -> b.ts -> a.ts`) | `[path]`, `-j/--json` | | `export` | Export the whole code graph as NetworkX node-link JSON | `[path]`, `-o/--out <file>`, `--no-centrality` | Each subcommand's output / JSON shape follows a fixed contract (reference line numbers annotated in the source comments). ### `codegraph install` / `uninstall` — wire up AI agents `install` writes the codegraph MCP server entry into each supported agent's config file (no hand-editing JSON/TOML); `uninstall` reverses it. Supported agents (`ALL_TARGETS` order): **Claude Code, Cursor, Codex CLI, opencode, Hermes Agent, Gemini CLI, Antigravity IDE, Kiro**. The written MCP command launches the **Rust binary**: `command: "codegraph"`, `args: ["serve", "--mcp"]` (Cursor also injects `--path`). ```bash codegraph install --yes # auto-detect installed agents, global codegraph install --target=claude,cursor --yes # explicit list codegraph install --target=auto --local # detected agents, project-local codegraph install --print-config cursor # print the snippet only, no write codegraph uninstall --target=claude --local # remove one agent's local config ``` Idempotent (upsert by the `codegraph` key); `uninstall` removes only codegraph's own entry/section and leaves other MCP servers intact. Instruction files are delimited by `<!-- CODEGRAPH_START -->`/`<!-- CODEGRAPH_END -->` markers. The interactive multiselect TUI is not provided — this is non-interactive, flag-driven (defaults to `auto` when no `--target`). ### `codegraph export` — whole-graph export + centrality Export the entire code graph as **NetworkX node-link JSON** (`{directed, multigraph, graph, nodes, links, edges}`) for visualization, global analysis, or feeding external tools / LLMs. ```bash codegraph export --path . --out graph.json # with deterministic centrality (default) codegraph export --path . # print to stdout codegraph export --path . --no-centrality # skip the PageRank pass (faster on huge graphs) ``` - Node fields: `id` / `label`(=name) / `kind` / `file_type` (`File` -> `"file"`, other symbols -> `"code"`) / `source_file`(=file_path) / `qualified_name` / `language` / `start_line` / `end_line` / `signature`; with centrality, also `pagerank` / `god_score`(=pagerank) / `in_degree` / `out_degree`. - Edges are emitted under both `links` (the canonical NetworkX key) and `edges` (an alias), with fields `source` / `target` / `relation`(=kind) / `kind` / `line` / `metadata`. - **Centrality is a deterministic pure-Rust PageRank** (damping 0.85, fixed 30 iterations, id-sorted order -> byte-reproducible), computed over dependency edges only (excluding structural `contains` edges). No ML/vector crates, so it stays within the no-AI hard constraint. Higher `god_score` = more central ("god node"), i.e. higher change-risk / read-priority. --- ## MCP Server (10 tools) `codegraph serve --mcp` runs a newline-delimited JSON-RPC MCP server over stdin/stdout (**not** LSP `Content-Length` framing). `initialize` returns `protocolVersion: "2024-11-05"`, `serverInfo.name: "codegraph"`. The default `tools/list` surfaces only the **4 core tools** (`explore`/`node`/`search`/`callers`, the `DEFAULT_MCP_TOOLS` set); the rest stay callable via `tools/call` and can be listed via the `CODEGRAPH_MCP_TOOLS` env var (comma-separated short names). All 10 tools: | Tool | Purpose | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `codegraph_search` | FTS5 + multi-signal scored symbol search. | | `codegraph_callers` | Callers of a symbol. | | `codegraph_callees` | Targets a symbol calls. | | `codegraph_impact` | Blast radius of changing a symbol. | | `codegraph_node` | Node detail (symbol view) or file view (line-numbered source). | | `codegraph_explore` | PRIMARY tool: blast radius + relationship map + dynamic-dispatch boundaries + source blocks (output is size-adaptive to project scale). | | `codegraph_status` | Index status summary. | | `codegraph_files` | List/tree indexed files. | | `codegraph_check` | Circular-dependency detection (additive tool). | | `codegraph_export` | Whole-graph node-link JSON export (additive tool). | Error channels: unknown **tool name** -> JSON-RPC error `-32602`; missing/invalid **required argument** -> tool result `{content, isError:true}` with `Error: <msg>`. ```jsonc { "mcpServers": { "codegraph": { "command": "codegraph", "args": ["serve", "--mcp", "-p", "/abs/path/to/your/project"], }, }, } ``` Or run `codegraph install --target=claude --local` to write this automatically. --- ## Using CodeGraph with an LLM CodeGraph itself has **no built-in LLM** (the no-AI hard constraint), but it is designed to _feed_ one. The recommended division of labor: - CodeGraph produces **deterministic** structural facts (graph / subgraph / centrality / call relationships / blast radius) — millisecond-fast, reproducible, zero LLM cost; - an external LLM / agent reasons only over the **already-located small context** (diagnosis / summary / suggestions). Two ways to combine them (neither violates the guardrail): 1. **MCP**: an agent (Claude, Cursor, …) calls codegraph's MCP tools; the LLM reasoning lives in the agent. 2. **Backend orchestration**: your service calls codegraph `export`/`explore` to get the graph, then feeds your own LLM. A runnable example lives at [`examples/llm_orchestration.py`](examples/llm_orchestration.py): it pulls the top god-nodes (centrality) via `export` + a relevant subgraph via `codegraph_explore` (MCP), assembles a prompt, and feeds an OpenAI-compatible LLM for diagnosis / summary. It is dry-run by default (prints the prompt only): ```bash python examples/llm_orchestration.py --repo . --query "how does indexing work" # real call: export OPENAI_API_KEY=... then add --call-llm ``` > The guardrail only forbids embedding an LLM library _inside_ the codegraph > binary (which would break determinism, byte-reproducibility, and zero cost — and > is exactly why LLM-based extractors are slow). MCP use and backend orchestration > are unrestricted and are codegraph's intended role. --- ## Supported Languages The language set is the fixed `LANGUAGES` set, in three extraction tiers: **tree-sitter grammars (regular symbol extraction):** TypeScript, TSX, JavaScript, JSX, Python, Go, Rust, Java, C, C++, C#, PHP, Ruby, Swift, Kotlin, Dart, Pascal, Scala, Lua, Luau, Objective-C, R. **embedded / custom extractors:** Vue, Svelte, Astro, Razor, Liquid, MyBatis XML, DFM/FMX. **file-level-only (0 symbols at the extract stage):** YAML, Twig, Properties. > Scope note: `html`/`css`/`json`/`sql` are **not** in the extraction model, so > they are not extracted. See > [`docs/grammar-manifest.md`](docs/grammar-manifest.md) and > [`docs/embedded-extraction.md`](docs/embedded-extraction.md). --- ## Scope & Non-Goals **Does:** deterministic code-structure extraction, cross-file resolution, graph traversal, FTS5 search, whole-graph export / centrality, MCP/CLI surfaces, and golden byte-stable output. **Does not (explicitly excluded):** - No AI / vector / embedding / LLM path anywhere inside the binary (hard constraint, guardrail-enforced; LLM combination happens in the orchestration layer — see above). - No semantic search; search is FTS5 + deterministic scoring only. - Concrete `FrameworkResolver`s exist for React/Vue/NestJS; other framework resolution is deferred (see [`KNOWN_DIFFS.md`](KNOWN_DIFFS.md)). - No languages beyond the fixed `LANGUAGES` set. --- ## Documentation - [`docs/architecture.md`](docs/architecture.md) — crate dependency graph, extraction/resolution/traversal/search pipelines, MCP/CLI surfaces, daemon/watch lifecycle. - [`docs/data-model.md`](docs/data-model.md) — SQLite/FTS5 storage contract. - [`docs/equivalence.md`](docs/equivalence.md) — the 3-tier method, node-id / content-hash contract, golden regeneration, `KNOWN_DIFFS.md` rule format. - [`docs/grammar-manifest.md`](docs/grammar-manifest.md) / [`docs/embedded-extraction.md`](docs/embedded-extraction.md) — languages / extraction. - [`KNOWN_DIFFS.md`](KNOWN_DIFFS.md) — registered Tier-3 presentation diffs (read at runtime by the equivalence oracle). - [`examples/`](examples/) — codegraph -> LLM orchestration example. - [`docs/readme/README.zh-CN.md`](docs/readme/README.zh-CN.md) — 中文说明. --- ## License MIT — see [`LICENSE-MIT`](LICENSE-MIT).