CodeGraph

# CodeGraph

**Cross-language code intelligence for AI agents and developers.**

[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)

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

```json
{
  "mcpServers": {
    "codegraph": {
      "command": "/path/to/codegraph-server",
      "args": ["--mcp"]
    }
  }
}
```

The server indexes the current working directory automatically.

### VS Code Extension

Install the VSIX:

```bash
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](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](https://github.com/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`](.github/workflows/codegraph-pr.yml)
into your repo. The core invocation is a single command:

```bash
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

| 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. Takes a value: `--full-body-embedding=false` turns it off |
| `--split-identifiers` | `true` | Also embed the word-split form of identifiers whose words are run together, so `getUserById` embeds as "get user by id" too. Names already separated by `_` or `-` are left alone, since they tokenise into the same words; a leading or trailing delimiter separates nothing, so `_handleClick` is split like `handleClick`. Takes a value: `--split-identifiers=false` embeds raw names, as releases up to 0.20.1 did |
| `--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 and memory tools 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>'`. |

`--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](#upgrading-to-021).

#### `--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](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`, `.ven