CodeGraph
Cross-language code intelligence for AI agents and developers.
CodeGraph builds a semantic graph of your codebase — functions, classes, imports, call chains — and exposes it through 45 MCP tools, a VS Code extension, and a persistent memory layer. Parses 37 languages via tree-sitter. AI agents get structured code understanding instead of grepping through files.
Quick Start
MCP Server (Claude Code, Cursor, any MCP client)
Add to ~/.claude.json (or your MCP client config):
{
"mcpServers": {
"codegraph": {
"command": "/path/to/codegraph-server",
"args": ["--mcp"]
}
}
}
The server indexes the current working directory automatically.
VS Code Extension
Install the VSIX:
code --install-extension codegraph-0.14.0.vsix
The extension starts the server automatically and registers all tools as Language Model Tools for Copilot.
Rules for AI agents
Pre-configured rule files that teach AI coding agents (Claude, Cursor,
Windsurf, Codex, Cline) to use CodeGraph MCP tools before falling back
to grep / multi-file reads. Maps natural-language intent to the right
codegraph_* tool.
→ codegraph-ai/codegraph-rules-for-agents
Setup is cp <agent>/codegraph.md ~/<agent>/ (one line per agent — see
the rules repo's README).
GitHub Action — PR review in CI
Drop a workflow into your repo to get an automatic code-graph analysis
comment on every PR — blast radius, test gaps, stale docs, suggested
reviewers. Runs graph-only (no embeddings, no ONNX model), so it's
fast and needs no API keys — just the built-in GITHUB_TOKEN.
Copy .github/workflows/codegraph-pr.yml
into your repo. The core invocation is a single command:
codegraph-server --graph-only \
--run-tool codegraph_pr_context \
--tool-args '{"baseBranch":"main","format":"markdown"}'
This prints a ready-to-post markdown comment. The --graph-only flag
skips embedding generation (10-50× faster indexing); --run-tool runs
one tool and exits without the MCP stdio handshake — ideal for scripting.
Configuration
MCP Server flags
| Flag | Default | Description |
|---|---|---|
--workspace <path> | current dir | Directories to index (repeatable for multi-project) |
--exclude <dir> | — | Directories to skip (repeatable) |
--embedding-model <model> | bge-small | bge-small (384d, fast), jina-code-v2 (768d, 6× slower), granite-97m (384d, 32K ctx, ~3× slower), or static (model2vec, 256d — ~100× faster indexing, no ONNX; needs a local model dir, see below) |
--full-body-embedding | true | Embed full function body (~50 lines) for better semantic search and duplicate detection |
--max-files <n> | 5000 | Maximum files to index |
--profile <name> | all | Filter the exposed MCP tool surface to a named subset (see below) |
--graph-only | off | Skip embedding generation — build the graph and serve structural tools only. No ONNX model load, 10-50× faster indexing. Semantic search unavailable. For CI / one-shot graph queries. |
--run-tool <name> | — | One-shot mode: index, run a single tool, print its result, exit. No MCP handshake. Pair with --tool-args '<json>'. |
--embedding-model static — model2vec fast indexing
Static (model2vec) embeddings replace the ONNX transformer with a token→vector
lookup table: indexing is ~100× faster (this repo's 5,873 symbols embed in
~1 s vs ~3.4 min with BGE) and there's no ONNX runtime or 1.5 GB RAM gate.
Retrieval stays hybrid (BM25 + semantic), so end-to-end quality is ~90% of
BGE. The VS Code extension ships the model bundled, so static works there
with no setup. For the CLI/MCP server it needs a local model directory
(config.json + tokenizer.json + model.safetensors):
- Point at it with
CODEGRAPH_STATIC_MODEL=/path/to/model(or the VS Codecodegraph.staticModelPathsetting to override the bundled model). Default:~/.codegraph/static_models/jina-code-static-256. - Distill one from any sentence-transformer (Apache-2.0 Jina-Code by default) in
~30 s on CPU:
python scripts/distill_static_model.py.
--profile — narrow the MCP tool surface
The full 32-tool surface is convenient but inflates the agent's prompt-context cost. A profile exposes only the slice you need (also settable via the CODEGRAPH_TOOL_PROFILE env var):
| Profile | Tools | Use when |
|---|---|---|
all (default) | every tool (community + pro) | normal sessions |
core | 8 — search + symbol info + AI context | chatty agent sessions where you only need lookups |
graph | 16 — callers/callees/deps/impact/traverse | refactoring + structural analysis |
memory | 7 — codegraph_memory_* only | note-taking / knowledge-base workflows |
security | pro security tools only (empty on community) | pro security audits |
VS Code settings
{
"codegraph.indexOnStartup": true,
"codegraph.indexPaths": ["/path/to/project-a", "/path/to/project-b"],
"codegraph.excludePatterns": ["**/cmake-build-debug/**", "**/generated/**"],
"codegraph.embeddingModel": "bge-small", // or "static" for ~100× faster indexing
"codegraph.staticModelPath": "", // model2vec model dir when embeddingModel is "static"
"codegraph.maxFileSizeKB": 1024,
"codegraph.debug": false
}
Full-body embeddings are enabled by default. Function body text is captured at parse time with zero I/O overhead.
Built-in exclusions (always skipped) cover ~47 directories across three categories:
- Build / cache:
node_modules,target,dist,build,out,.git,__pycache__,vendor,.venv,venv,.tox,.pytest_cache,.mypy_cache,.ruff_cache,.next,.nuxt,.svelte-kit,.parcel-cache,.npm,.yarn,.pnpm-store,.cache,.cargo,.bundle,.gradle,DerivedData,Pods,xcuserdata,cmake-build-* - IDE / IaC state:
.idea,.vscode-test,.fleet,.terraform,.terragrunt-cache,.serverless - Sensitive credential dirs:
.aws,.ssh,.gnupg,.kube,.docker
Plus glob patterns for binary archives, native libraries, OS metadata, and secret file extensions (*.pem, *.key, *.p12, *.pfx, *.crt, *.gpg, *.kdbx, SSH key conventions like id_rsa, etc.) — defense in depth against accidentally embedding credentials.
Tools (42 community + 27 pro, 17 security)
Code Analysis (11)
| Tool | What it does |
|---|---|
get_ai_context | Primary context tool. Intent-aware (explain/modify/debug/test) with token budgeting. Returns source, related symbols, imports, siblings, debug hints. |
get_edit_context | Everything needed before editing: source + callers + tests + memories + git history |
get_curated_context | Cross-codebase context for a natural language query ("how does auth work?") |
analyze_impact | Blast radius prediction — what breaks if you modify, delete, or rename |
analyze_complexity | Cyclomatic complexity with breakdown (branches, loops, nesting, exceptions, early returns) |
find_circular_deps | Detect circular import/dependency chains across files |
find_hot_paths | Most-called functions ranked by transitive caller count |
find_dead_imports | Find unused imports — modules imported but never referenced |
get_module_summary | High-level summary of a directory: file count, functions, language breakdown, top complex functions |
search_by_pattern | Regex search across function bodies, signatures, names, and docstrings |
search_by_error | Find functions that throw, catch, or handle specific error types |
Code Navigation (13)
| Tool | What it does |
|---|---|
symbol_search | Find symbols by name or natural language (hybrid BM25 + semantic search) |
get_callers / get_callees | Who calls this? What does it call? (with transitive depth) |
get_detailed_symbol | Full symbol info: source, callers, callees, complexity |
get_symbol_info | Quick metadata: signature, visibility, kind |
get_dependency_graph | File/module import relationships with depth control |
get_call_graph | Function call chains (callers and callees) |
find_by_imports | Find files importing a module |
find_by_signature | Search by param count, return type, modifiers |
find_entry_points | Main functions, HTTP handlers, CLI commands, event handlers |
find_implementors | Find all functions registered as ops struct callbacks |
find_related_tests | Tests that exercise a given function |
traverse_graph | Custom graph traversal with edge/node type filters |
Indexing (3)
| Tool | What it does |
|---|---|
reindex_workspace | Full or incremental workspace reindex |
index_files | Add/update specific files without full reindex |
index_directory | Add directory to graph alongside existing data |
Memory (7)
Persistent AI context across sessions — debugging insights, architectural decisions, known issues.
| Tool | What it does |
|---|---|
memory_store / memory_get / memory_search | Store, retrieve, search memories (BM25 + semantic) |
memory_context | Get memories relevant to a file/function |
memory_list / memory_invalidate / memory_stats | Browse, retire, monitor |
Pairs well with Tempera — an episodic memory system that captures transferable debugging strategies and solutions across projects. CodeGraph's memory tools store project-scoped notes; Tempera captures cross-project BKMs (best-known methods) that improve over time.
PR / Change Analysis (1)
| Tool | What it does |
|---|---|
pr_context | One-call PR review. Runs git diff against base branch, finds changed functions in the graph, reports: blast radius (callers), test coverage + gaps, affected modules, diff-aware change classification (signature vs body), stale-doc warnings, complexity, commit-message hint, suggested reviewers from git blame. |
Documentation (7)
Persistent project documentation — index design docs, search them semantically, verify code matches the design, generate architecture docs from the code graph.
| Tool | What it does |
|---|---|
index_markdown | Index a local .md file (ARCHITECTURE.md, API_DESIGN.md, etc.) into the persistent docs store. Heading-tree chunking with leaf-node embeddings. |
search_docs | Semantic search over indexed docs — returns matching sections with heading-path breadcrumbs |
list_doc_sources | List all indexed source files |
remove_doc_source | Remove all indexed chunks from a source file |
verify_design | Cross-reference doc claims vs code graph. direction=forward (doc→code), reverse (code→doc), or both |
design_gaps | Find identifiers described in docs that don't exist in code yet — build TODO lists from specs |
generate_architecture_doc | Auto-generate a structured ARCHITECTURE.md from the live code graph (modules, hot paths, complexity, circular deps) |
All tool names are prefixed with codegraph_ (e.g. codegraph_get_ai_context). Tools that target a specific symbol accept uri + line or nodeId from symbol_search results.
Usage examples
Index a design doc and search it:
codegraph_index_markdown(path: "/projects/myapp/docs/ARCHITECTURE.md")
codegraph_search_docs(query: "how does the auth module handle JWT refresh?")
Check if the code matches the design:
codegraph_verify_design(source: "/projects/myapp/docs/ARCHITECTURE.md", direction: "forward")
// → "132/132 identifiers verified, 0 gaps"
Find what's described in docs but not yet implemented:
codegraph_design_gaps(source: "/projects/myapp/docs/API_DESIGN.md")
// → "4 of 12 identifiers not found in code: PaymentService, RefundHandler, ..."
Generate architecture docs from the code graph:
codegraph_generate_architecture_doc(scope: "src/", topN: 5)
// → Markdown with modules, complexity hotspots, hot paths, circular deps
Save a debugging insight for future sessions:
codegraph_memory_store(kind: "debug_context", title: "Nginx body size limit",
content: "The /upload endpoint fails on payloads > 1MB...",
problem: "API returns 500 on large uploads",
solution: "Increase nginx client_max_body_size to 10M",
agentSource: "claude")
Get AI context with graph compression stats + design doc augmentation:
codegraph_get_ai_context(uri: "file:///projects/myapp/src/auth.rs", line: 42, intent: "modify")
// → Code context + graphStats: {entitiesInGraph: 13555, entitiesTraversed: 47, entitiesKept: 8}
// → design_context section from indexed docs mentioning "auth"
Review a PR — blast radius, test gaps, stale docs, reviewers in one call:
codegraph_pr_context(baseBranch: "main")
// → "PR changes 4 files (+263/-77, 12 functions). 37 direct callers, 8 tests, 3 untested. Risk: medium."
// → test_gaps: [refresh_token, revoke_session] — functions with 0 test callers
// → stale_docs: ["auth.rs described in ARCHITECTURE.md > Authentication — doc may need updating"]
// → suggested_reviewers: [{author: "anvanster", lines_owned: 3200}]
// → commit_hint: "feat(mcp): <describe the change>"
Narrow the tool surface for chatty sessions:
codegraph-server --mcp --profile=core # Only 8 tools: search + symbol info + AI context
CodeGraph Pro
Additional tools available in CodeGraph Pro:
| Tool | What it does |
|---|---|
scan_security | Security vulnerability scan: 40+ dangerous function patterns, source-to-sink taint tracing, auth coverage for HTTP endpoints (7 languages/frameworks), architectural layer violations, weak crypto, hardcoded secrets |
analyze_coupling | Module coupling metrics and instability scores |
find_unused_code | Dead code detection with confidence scoring |
find_duplicates | Detect duplicate/near-duplicate functions |
find_similar / cluster_symbols / compare_symbols | Embedding-based code similarity |
cross_project_search | Search across all indexed projects |
mine_git_history / mine_git_history_for_file / search_git_history | Git history mining and semantic search |
security_control_flow | Map every execution path through a function — "can this return without hitting the auth check?" |
security_trace_data_flow | Follow a variable from birth to death — "does user input reach this SQL query?" |
security_generate_sbom | CycloneDX SBOM from 8 lockfile formats |
security_audit_deps | OSV vulnerability check on dependencies |
security_check_unchecked_returns / _resource_leaks / _misconfig / _input_validation / _error_exposure | 5 heuristic analyzers covering ~80% of CWE Top 25 |
security_scan_iac | Docker / Kubernetes / Terraform misconfiguration scan |
security_check_licenses | Lockfile license policy enforcement (copyleft detection) |
security_check_secrets_entropy | Shannon-entropy hardcoded-secret detection |
security_detect_injection | Focused SQL/XSS/cmd/path/deser/template injection detection (20 patterns) |
security_check_search_path | Untrusted search-path / DLL-hijacking detection (CWE-426/CWE-427) |
security_check_crypto | Cryptographic misuse: weak ciphers/hashes/PRNG/keys, static IVs, timing-leak comparisons (CWE-208/326-330/338/916, 35 patterns) |
security_export_sarif | Aggregate findings as SARIF 2.1.0 (GitHub Code Scanning, GitLab SAST) |
Cross-cutting features (all security_check_* tools):
include_tests/treat_as_production— first-class skip for tests/samples/vendoredcheck_compile_gates— C/C++ findings inside#ifdef Xare marked DEFENSIVE_GATED_OFF when X isn't defined by CMake/Cargo/Makefile- 25-marker suppression honoring (
# nosec,// NOLINT,// codeql[ignore],# rubocop:disable, etc.) at line and function level - Telemetry blocks per scan:
path_filter(examined/matched/skipped) +compile_gate(gated_off count)
Languages
38 languages parsed via tree-sitter — functions, classes, imports, call graph, complexity metrics, dependency graphs, symbol search, and impact analysis:
| Category | Languages |
|---|---|
| Systems | C, C++, Rust, Zig, Objective-C |
| JVM | Java, Kotlin, Scala, Groovy, Clojure |
| Web/Scripting | TypeScript/JS, Python, Ruby, PHP, Perl, Lua, Elixir, Elm |
| Web/Style | CSS |
| Mobile | Swift, Dart |
| Functional | Haskell, OCaml, Julia, Erlang, Elm, Clojure |
| Enterprise | C#, COBOL, Fortran, Go |
| Blockchain | Solidity |
| Shell/Config | Bash, HCL/Terraform, TOML, YAML |
| Hardware | Verilog/SystemVerilog, Tcl |
| Data Science | R, Julia |
HTTP handler detection: Python (FastAPI/Flask/Django), TypeScript (NestJS), Java (Spring/JAX-RS), Go (stdlib/Gin/Echo/Fiber), C# (ASP.NET), Ruby (Rails), PHP (Laravel/Symfony).
Community vs full builds: COBOL, Fortran, Perl, Dart, Zig, and R are compiled only with
--features extra-languages. The default community binary omits them — they had zero usage in telemetry and their tree-sitter grammars add ~25 MB (COBOL's parse tables alone are 30 MB). The other 32 languages are always available.
Architecture
MCP Client (Claude, Cursor, ...) VS Code Extension
| |
MCP (stdio) LSP Protocol
| |
└───────────┐ ┌───────────┘
▼ ▼
┌─────────────────────────────┐
│ codegraph-server │
├─────────────────────────────┤
│ 38 tree-sitter parsers │
│ Semantic graph engine │
│ AI query engine (BM25) │
│ Memory layer (RocksDB) │
│ Docs store (RocksDB+HNSW) │
│ Full-body embeddings (BGE) │
│ HNSW vector index │
└─────────────────────────────┘
A single Rust binary serves both MCP and LSP protocols.
- Indexing: ~60 files/sec. Incremental re-indexing on file changes via FNV-1a content hashing.
- Persistence: Graph and embeddings persist to
~/.codegraph/graph.db(RocksDB). Instant startup on restart — no re-parsing, no re-embedding. - Queries: Sub-100ms. Cross-file import and call resolution at index time.
- Embeddings: Full-body (function bodies captured at parse time, zero disk I/O). Vectors stored in RocksDB alongside the graph. Auto-downloads model on first run.
Building from Source
git clone https://github.com/codegraph-ai/codegraph
cd codegraph
cargo build --release -p codegraph-server # Rust server
cd vscode && npm install && npm run esbuild # VS Code extension
npx @vscode/vsce package # VSIX
Requires Rust stable, Node.js 18+, VS Code 1.90+.
Support the project
CodeGraph is free, open-source, and maintained by a solo developer. If it saves you time, consider sponsoring on GitHub — it helps keep the project alive and growing.
License
Apache-2.0