CodeGraph-Rust
Deterministic code intelligence for agents and developers.
Tree-sitter extraction, SQLite/FTS5 search, graph traversal, CLI, and MCP in one native binary. No AI or vector runtime inside the indexer.
English · 简体中文 · Website · Documentation · Browser viewer · Community · Contributing
Why CodeGraph
CodeGraph turns a source tree into a local knowledge graph: symbols become nodes; calls, imports, inheritance, ownership, references, and type relationships become edges. The graph is persisted per project and can be queried without asking an LLM to rediscover structure through repeated text searches.
- Deterministic: no model calls, embeddings, or vector search; canonical graph output is guarded by byte-stable golden fixtures.
- Source-aware: search, callers/callees, impact, file source, and multi-file exploration use one indexed representation.
- Agent-ready: an MCP server exposes the same graph and verbatim source used by the CLI.
- Visual (preview): a local browser viewer reads the same index: a symbol's callers, source and callees side by side, call paths, an architecture map, type hierarchies and the code nothing reaches.
- Local-first: the index lives under the project; the shared daemon and HTTP transport are local processes.
- Broad language coverage: grammar-backed languages, embedded/template files, and framework-aware Godot/Tauri/JS ecosystem relationships share one schema.
- Incremental:
syncand the watcher update changed files while preserving the same final canonical result as a clean index.
Exact language and static-analysis boundaries are documented in
docs/languages.md.
Install
Verified release installer
The installers select the platform archive, require its entry in SHA256SUMS,
verify the checksum, and then install the binary.
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/install.sh | sh
# Windows PowerShell 5.1+
irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/main/scripts/install.ps1 | iex
Pin an exact release when reproducibility matters:
curl -fsSL https://raw.githubusercontent.com/sunerpy/codegraph-rust/vX.Y.Z/scripts/install.sh \
| CODEGRAPH_VERSION=vX.Y.Z sh
$env:CODEGRAPH_VERSION = "vX.Y.Z"
irm https://raw.githubusercontent.com/sunerpy/codegraph-rust/vX.Y.Z/scripts/install.ps1 | iex
Prebuilt archives
GitHub Releases publish these archive families:
The Linux archives are static musl builds that allocate through mimalloc; the macOS and Windows archives use the platform allocator.
Each release also includes SHA256SUMS. GitHub CLI users can additionally verify
an archive's build provenance:
gh attestation verify codegraph-X.Y.Z-x86_64-unknown-linux-musl.tar.gz \
--repo sunerpy/codegraph-rust \
--signer-workflow sunerpy/codegraph-rust/.github/workflows/release.yml \
--deny-self-hosted-runners
Build from Git
The project is not published to crates.io:
cargo install --locked --git https://github.com/sunerpy/codegraph-rust codegraph-rs
The installed executable is codegraph; SQLite is bundled.
Quickstart
Create an index, check its state, then ask a structural question:
cd /path/to/project
codegraph init .
codegraph status . --json
codegraph search "main" -p .
codegraph explore "startup and configuration flow" -p .
Lifecycle commands take a positional project path. Research commands take one
query or target plus -p/--path. For example:
codegraph sync .
codegraph node "ReferenceResolver" -p .
codegraph callers "ReferenceResolver" -p .
codegraph impact "ReferenceResolver" -p .
If a command rejects an argument, run codegraph <command> --help; do not abandon
an available index because a lifecycle and research command use different path
syntax.
CLI
Common workflows:
# Index lifecycle
codegraph status . --json
codegraph sync .
codegraph index . # full rebuild of the selected project
# Research
codegraph search "symbol" -p .
codegraph explore "area or flow" -p .
codegraph node "symbol-or-id" -p .
codegraph files -p . --format tree
# Relationships
codegraph callers "symbol" -p .
codegraph callees "symbol" -p .
codegraph impact "symbol" -p .
# Operations
codegraph serve --mcp --path .
codegraph serve --http --path .
codegraph mcp list
codegraph http list
query remains an alias for search. For every command and flag, see
docs/cli.md.
MCP
Register the stdio server manually:
{
"mcpServers": {
"codegraph": {
"command": "codegraph",
"args": ["serve", "--mcp"],
},
},
}
Or let the installer update supported agent configurations:
codegraph install --yes
codegraph install --yes --init
codegraph install --target=codex,claude,kiro --yes
Global profile overrides are honored: Claude Code follows
CLAUDE_CONFIG_DIR, Codex follows CODEX_HOME, and OpenCode 2 receives its
native mcp.servers.codegraph entry with codemode: false. Claude entries set
alwaysLoad: true; Copilot CLI entries set deferTools: "never" so Explore is
available from the first prompt.
A server launched without --path can serve an existing index selected by an
explicit per-call projectPath, client roots, or deterministic workspace
adoption. First explicit access to an existing index waits for catch-up and
retains that project's shared daemon/watcher; multiple child projects remain
separate and multiple MCP sessions share one writer per project. Pin --path
when a project should be the default rather than supplied per call. Explicit
direct mode (CODEGRAPH_NO_DAEMON=1) opts out of lazy cross-project daemon
services, permits one direct writer, and rejects a second.
The default visible MCP surface emphasizes exploration, file/symbol reads,
search, and callers. Additional known tools can be enabled with
CODEGRAPH_MCP_TOOLS. Tool schemas, project resolution, stdio/HTTP behavior,
and protocol compatibility are in docs/mcp.md.
Agents and IDEs
codegraph install supports common coding agents and IDE integrations. Some
clients can expand a workspace variable in global configuration; others require a
project-local absolute path for live watching. The installer prints the relevant
caveat rather than guessing.
codegraph install --target=auto --global --yes
codegraph install --target=auto --local --yes
codegraph init --target=kiro .
codegraph init --target=zed .
The optional embedded skill teaches an agent to use CodeGraph before grep/read:
codegraph skill install --yes
codegraph skill status
codegraph skill update --dry-run --diff
- Run
codegraph status <project> --jsonbefore research. - Use
codegraph_explorefirst for architecture, a bug, or a flow. - Use
codegraph_searchto locate one name andcodegraph_nodeto read one symbol or indexed file with its caller/callee trail. - Use
codegraph_impactbefore changing a shared symbol. - Trust the structural index; re-read only files explicitly reported stale.
- Use
codegraph sync <project>for ordinary catch-up. Rebuild only when status or a requested operation requires it.
Full target and configuration matrices:
docs/cli.md, docs/mcp.md, and
editors/zed/README.md.
Browser viewer
codegraph ui opens a local, read-only reader of the index in your browser. It is a
preview, refused unless CODEGRAPH_UI=1 is set:
CODEGRAPH_UI=1 codegraph ui # the indexed project you are in
CODEGRAPH_UI=1 codegraph ui --read-only # also refuse saving trails
It binds 127.0.0.1 only, never builds or changes the index, and writes nothing but
the trails you choose to save under .codegraph/ui/trails/. It has a dark and a light
theme and follows the system's until you pick one.
A tour of every view is on the website:
the browser viewer. The reference is
docs/ui.md.
Determinism and safety
The compatibility contract includes stable node IDs, canonical golden artifacts, SQLite schema parity, deterministic resolution and ordering, project-contained filesystem access, and fail-closed ambiguity. Incremental output is tested against a clean full index.
CodeGraph reports static evidence, not runtime certainty. Reflection, registries, event buses, framework conventions, generated code, and dynamic dispatch can continue beyond a known edge. Absence of a static reference is not proof that code is dead.
For schema and oracle details, read docs/data-model.md and
docs/equivalence.md. Security reports should follow
SECURITY.md.
Performance
Performance is measured by the committed benchmark harness on pinned corpora. A valid result records the implementation commits, environment, cache policy, run count, median, dispersion, and query percentiles. This README intentionally makes no floating latency claim.
Methodology and the current result status are in
docs/benchmark.md and
docs/benchmark-results.md.
Development
The pinned Rust toolchain and locked dependency graph are repository contracts. Start with:
git clone https://github.com/sunerpy/codegraph-rust.git
cd codegraph-rust
make hooks
make check
make check and make ci run the same complete local quality path; make pre-ci adds a local package/unpack/execute smoke. Focused targets are available through make help. Contributors should read
CONTRIBUTING.md and the canonical agent contract in
AGENTS.md.
Documentation
- firlab.app/codegraph — the website: guide, quick start and a tour of the viewer (简体中文)
docs/README.md— documentation mapdocs/architecture.md— workspace and runtime designdocs/cli.md— complete command referencedocs/mcp.md— MCP transports, tools, and clientsdocs/ui.md— local browser viewer (preview,CODEGRAPH_UI=1)docs/languages.md— language coverage and boundariesdocs/equivalence.md— deterministic golden contractdocs/upstream-sync/UPSTREAM.md— upstream ledgerdocs/troubleshooting.md— diagnostic workflow
Community
- Questions, bug reports and feature requests: GitHub Issues.
- WeChat: the Official Account 六月水蓝.
License
MIT — see LICENSE-MIT.
