Codegraph

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.

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.21.0.vsix

One VSIX serves every platform. The analysis engine is not bundled: on first activation the extension offers to download the engine built for your platform, verifies it against the published checksum, and installs it into ~/.codegraph/bin - the same location the JetBrains plugin uses, so one download serves both. The download is offered rather than performed automatically, because it is a native binary that runs with your permissions. Decline it and run CodeGraph: Download Analysis Engine from the command palette whenever you are ready.

Once an engine is present, the extension starts it automatically and registers all tools as Language Model Tools for Copilot.

JetBrains IDEs

A plugin for IntelliJ IDEA, PyCharm, GoLand, Android Studio and the rest of the family drives the same engine over LSP: Code Vision, Symbols and Memories tool windows, a graph panel, and one-click MCP registration for the AI Assistant. It resolves or downloads the engine the same way the VS Code extension does, sharing ~/.codegraph/bin.

→ jetbrains/README.md for surfaces, engine resolution order, and building from source.

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.

Upgrading to 0.21

Each project re-embeds once, in the background, the first time 0.21 opens it. Stored vectors now record the model and settings that built them, and an index from 0.20.1 or earlier records none. Keyword search keeps working while it runs.

Restart any --watch daemon after upgrading. A daemon left running keeps writing vectors that 0.21 will not load, and sessions attached to it run without semantic search until it restarts.

Identifiers whose words run together, like getUserById, are now also embedded in word-split form. This mostly helps natural-language search in camelCase languages such as TypeScript, Java and C#. Pass --split-identifiers=false to keep the old behaviour.

--full-body-embedding=false now takes effect; in 0.20.1 the flag was always on.

Configuration

MCP Server flags

--split-identifiers and --full-body-embedding both change the text every symbol is embedded from, and vectors built from different text cannot be ranked against each other. A project's stored vectors are therefore stamped with the settings that built them - --embedding-model included, since models differ in dimension - and are ignored by any process configured differently. Changing any of the three re-embeds in the background rather than requiring a manual reindex. Run --watch with the same flags as the sessions that read the project, so both sides share one set instead of re-embedding over each other. For what this means when upgrading from 0.20.1 or earlier, see Upgrading to 0.21.

--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):

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: