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 42 MCP tools, a VS Code extension, a JetBrains IDE plugin, and a persistent memory layer. Parses 38 languages via tree-sitter. AI agents get structured code understanding instead of grepping through files.
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 model is not bundled with any client — it needs a local model directory
(config.json + tokenizer.json + model.safetensors) at
~/.codegraph/static_models/jina-code-static-256, or wherever
CODEGRAPH_STATIC_MODEL points:
- Installing
@astudioplus/codegraph-mcp from npm downloads it into that
default location for you (best-effort; set CODEGRAPH_SKIP_MODEL_FETCH=1 to
skip, and the install never fails over it).
- Otherwise fetch the prebuilt one with
scripts/fetch-static-model.sh, or
distill your own from any sentence-transformer (Apache-2.0 Jina-Code by
default) in ~30 s on CPU: python scripts/distill_static_model.py.
- A model in the default location needs no IDE setting: both IDE clients leave
CODEGRAPH_STATIC_MODEL unset and let the engine resolve it. To use a model
kept somewhere else, set codegraph.staticModelPath in VS Code, or
Settings → Tools → CodeGraph → Embeddings → Static model directory in
JetBrains; each client then passes that path as CODEGRAPH_STATIC_MODEL.
CODEGRAPH_SKIP_MEMORY_CHECK — force the embedding model past the RAM gate
Before loading the ONNX model, the server checks available memory and, if under
~1.5 GB, skips the model to avoid an OOM-kill (running graph-only instead).
Set CODEGRAPH_SKIP_MEMORY_CHECK=1 (also accepts true/yes) to bypass that
check and always load the model.
Use it if embeddings are disabled even though the machine has plenty of free
RAM.
A reading of 0 MB available is treated as a detection failure and the model
loads anyway (macOS parks reclaimable memory in inactive/speculative pages that
some memory readers do not count as free), so this override is mainly for other
cases where the reported figure is low but wrong.
It works in both MCP and one-shot --run-tool modes.
--profile — narrow the MCP tool surface
The full 42-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 | 17 — callers/callees/deps/impact/traverse/PR context | refactoring + structural analysis |
memory | 14 — codegraph_memory_* plus the docs tools | note-taking / knowledge-base workflows |
security | pro security tools only (empty on community) | pro security audits |
VS Code settings
The codegraph.* settings are documented once, next to the extension that
reads them:
→ vscode/README.md — Configuration
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-*
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.
Indexing produced zero files, or something else looks wrong? See
docs/troubleshooting.md.
Tools
42 community tools, plus 27 more (17 of them security analyzers) in CodeGraph Pro.
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 |
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 |
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 |
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 X are 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, Dockerfile, 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 JetBrains Plugin
| | |
MCP (stdio) LSP Protocol 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.
Supported platforms
The engine is a native binary, downloaded for your platform on first run.
| Platform | Architectures |
|---|
| macOS | Apple Silicon (arm64) and Intel (x64) |
| Linux | x64 and arm64 |
| Windows | x64 (Windows on ARM runs the x64 build under emulation) |
Linux requires glibc 2.30 or newer and a libstdc++ from GCC 11 or newer
(GLIBCXX_3.4.29). The second requirement is the binding one, and it is not
implied by the first — the engine embeds ONNX Runtime, which is built with
GCC 11.
| Runs | Does not run |
|---|
| SLES 15 SP4 | Ubuntu 20.04 |
| Ubuntu 22.04 and newer | Debian 11 |
| Debian 12 and newer | RHEL / CentOS 8 |
| RHEL 9 and newer | Amazon Linux 2 |
| Amazon Linux 2023 | |
Both Linux architectures have identical requirements. If the engine exits
immediately with a message like
version `GLIBCXX_3.4.29' not found (required by codegraph-server)
the distribution's C++ runtime is older than the engine needs; installing a
newer libstdc++ (for example RHEL 8's gcc-toolset-11) resolves it without
upgrading the distribution.
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