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 · 简体中文 · Documentation · 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.
• 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: sync and 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:

Platform	Target	Archive
Linux x86_64	x86_64-unknown-linux-musl	.tar.gz
Linux ARM64	aarch64-unknown-linux-musl	.tar.gz
macOS Intel	x86_64-apple-darwin	.tar.gz
macOS Apple Silicon	aarch64-apple-darwin	.tar.gz
Windows x86_64	x86_64-pc-windows-msvc	.zip
Windows ARM64	aarch64-pc-windows-msvc	.zip

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

Compact guidance for coding agents

1. Run codegraph status <project> --json before research.
2. Use codegraph_explore first for architecture, a bug, or a flow.
3. Use codegraph_search to locate one name and codegraph_node to read one symbol or indexed file with its caller/callee trail.
4. Use codegraph_impact before changing a shared symbol.
5. Trust the structural index; re-read only files explicitly reported stale.
6. 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.

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

• docs/README.md — documentation map
• docs/architecture.md — workspace and runtime design
• docs/cli.md — complete command reference
• docs/mcp.md — MCP transports, tools, and clients
• docs/languages.md — language coverage and boundaries
• docs/equivalence.md — deterministic golden contract
• docs/upstream-sync/UPSTREAM.md — upstream ledger
• docs/troubleshooting.md — diagnostic workflow

License

MIT — see LICENSE-MIT.