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), or granite-97m (384d, 32K ctx, ~3× slower)
--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>'.

--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",
  "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/vendored
• check_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, 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).

---

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