Local-first semantic code graph for AI agents — tree-sitter parsing, global symbol IDs, call chains with control-flow markers, served over MCP. Single ~58 MB static binary.
CodeGraph parses your codebase with tree-sitter, builds a semantic graph where every symbol gets a global ID and every function has a call chain (markers + callee IDs), stores everything under .codegraph/ (SQLite by default), and exposes the graph to AI agents — Claude Code, Cursor, Codex CLI, opencode, Hermes, Antigravity — over the Model Context Protocol (MCP).
Agents that consult the semantic graph instead of grepping the filesystem make fewer tool calls, explore faster, and stay within context.
- Fewer tool calls — agents navigate call chains (
codegraph_flow), not grep - Local & fast — full re-index 139 files in ~190 ms, nothing leaves your machine
- Works everywhere — 14 languages, 6 storage backends, 24 MCP tools, one binary
- Semantic, not syntactic — symbols have global IDs; edges derived from call chains with markers (
LOOP,IF_TRUE,RETURN, …) - Binary analysis — builds call graphs directly from ELF/PE/Mach-O binaries via radare2, no source needed
# 1. Initialize and index your project
cd ~/code/my-project
codegraph init
# 2. Serve to your agent over MCP (stdio)
codegraph serve --mcp
# ... or over Streamable HTTP (for remote/Docker)
codegraph serve --mcp --http --addr 0.0.0.0:8123Reset generated index data without losing config.toml with codegraph clean (or remove the whole .codegraph/ with codegraph deinit).
The agent binds the workspace with codegraph_init {"path": ...} and gets tools like codegraph_search_symbol, codegraph_flow, codegraph_callers, codegraph_impact, codegraph_context — all querying over MCP.
| Tool | Type | Local-First | Semantic Graph | MCP Native | Multi-Storage | Binary Size |
|---|---|---|---|---|---|---|
| CodeGraph | Code graph + MCP | ✅ | ✅ (tree-sitter semgraph) | ✅ Built-in | ✅ 6 backends | ~58 MB |
| Aider RepoMap | Repo map generator | ✅ | ❌ (ctags-based) | ❌ | ❌ | N/A |
| Sourcegraph Cody | Cloud code search | ❌ (self-host) | ✅ (CodeQL) | Via extension | ❌ | N/A |
| Bloop | Code indexer | ✅ | ❌ (search only) | ❌ | ❌ | ~30 MB |
| CodeQL | Semantic analysis | ✅/Cloud | ✅ (QL queries) | ❌ | ❌ | Heavy |
| Kythe | Code graph | ✅ | ✅ | ❌ | ❌ | Complex setup |
| LSP servers | Per-language IDE | ✅ | Per-lang only | ❌ | ❌ | Per-lang |
| ast-grep | Structural search | ✅ | ❌ (pattern match) | ❌ | ❌ | ~10 MB |
| context7 | Docs MCP | ❌ | N/A | ✅ | ❌ | N/A |
→ Full comparison with decision matrix
CodeGraph supports parsing both source code (via tree-sitter) and configuration/document files:
14 languages: TypeScript · TSX · JavaScript · Python · Go · Rust · Java · C · C++ · C# · Ruby · PHP · Scala · Swift · Lua
| Format | Extension | Parser | Access |
|---|---|---|---|
| YAML | .yaml, .yml |
YamlParser | MCP |
| JSON | .json |
JsonParser | MCP |
| TOML | .toml |
TomlParser | MCP |
| HCL (HashiCorp) | .hcl, .tf |
HclParser | MCP |
Document files can be ingested into a document graph and queried via:
- MCP:
codegraph_graphdoc_ingest,codegraph_graphdoc_search,codegraph_graphdoc_hydrate,codegraph_graphdoc_list,codegraph_graphdoc_stats - GraphQL:
docList,docSearch,docStatsqueries anddocIngest,docSearch,docStatsmutations
- 24 MCP tools —
search_symbol,flow,callers,callees,impact,search_flow,context,references,diff,sandbox,mermaid, and more - 14 languages — TypeScript · TSX · JavaScript · Python · Go · Rust · Java · C · C++ · C# · Ruby · PHP · Scala · Swift · Lua
- 6 storage backends — SQLite (default), LMDB, Redis, Postgres, MySQL, Memory
- Semantic search — opt-in fastembed (BGE-small) for hybrid KNN + keyword search
- Behavior sandbox — JIT compile function groups + run against Rhai mocks
- Binary analysis via radare2 — extracts functions, imports, strings and call chains (with IF/LOOP/RETURN/THROW markers) from ELF, PE and Mach-O binaries; requires
radare2onPATH(skipped with a warning if missing, checkcodegraph doctor) - Full re-index always — watcher debounces changes, re-indexes completely (simpler, no stale state)
Automatic (recommended)
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/hungpham10/codegraph-rs/main/scripts/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/hungpham10/codegraph-rs/main/scripts/install.ps1 | iexOther options: Homebrew • AUR • .deb/.rpm • cargo install --git https://github.com/hungpham10/codegraph-rs codegraph
# .codegraph/config.toml
[storage]
type = "sqlite" # or lmdb, redis, postgres, mysql, memory
[embedding]
# backend = "fastembed" # enable semantic/hybrid search
[binary]
# enabled = true # analyze binaries with radare2 (requires r2 on PATH)
# depth = "aaa" # "aaa" (full) | "fast" (af + aar + aac)Full config reference → | Storage backends → | Semantic search → | Binary analysis →
files → tree-sitter (rayon) ──┐
├→ semgraph (global IDs + chains)
binaries → radare2 (r2pipe) ──┘
→ GraphIndex (2 engines + pluggable storage)
→ MCP server (24 tools) → AI Agent
| Topic | File |
|---|---|
| Architecture & Pipeline | docs/architecture.md |
| Extraction & Languages | docs/specs/04-extraction.md |
| Storage & GraphIndex | docs/specs/03-db-layer.md |
| MCP Server & Tools | docs/specs/07-mcp-server.md |
| CLI & Watcher | docs/specs/09-cli-watcher.md |
| Semgraph Model | docs/specs/02-core-types.md |
| Installer Details | docs/specs/08-installer.md |
| Full Comparison | docs/comparison.md |
| Configuration Reference | docs/configuration.md |
| Storage Backends | docs/storage-backends.md |
| Semantic Search | docs/semantic-search.md |
| Binary Analysis (radare2) | docs/binary-analysis.md |
| Why Rust (Rewrite Story) | docs/why-rust.md |
| Development Guide | docs/development.md |
cargo build --workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --allSee Development Guide for feature flags, per-crate tests, and release process.
You can buy me a coffee by sending me money by MOMO
MIT. See LICENSE.
- Original TypeScript implementation by @colbymchenry
tree-sitterand all language grammar authorsrusqlite,notify,clap,tokio,rayon,ignore,dashmap,parking_lot