Quick Start

pip install code-review-graph                     # or: pipx install code-review-graph
code-review-graph install          # auto-detects and configures all supported platforms
code-review-graph build            # parse your codebase

One command sets up everything. install detects which AI coding tools you have, writes the correct MCP configuration for each one, installs platform-native hooks/skills where supported, and injects graph-aware instructions into your platform rules. It auto-detects whether you installed via uvx or pip/pipx and generates the right config. Restart your editor/tool after installing.

<p align="center"> <img src="diagrams/diagram8_supported_platforms.png" alt="One Install, Every Platform: auto-detects Codex, Claude Code, Cursor, Windsurf, Zed, Continue, OpenCode, Antigravity, Gemini CLI, Qwen, Qoder, Kiro, and GitHub Copilot" width="85%" /> </p>

To target a specific platform:

code-review-graph install --platform codex       # configure only Codex
code-review-graph install --platform cursor      # configure only Cursor
code-review-graph install --platform claude-code  # configure only Claude Code
code-review-graph install --platform gemini-cli   # configure only Gemini CLI
code-review-graph install --platform kiro         # configure only Kiro
code-review-graph install --platform copilot      # configure only GitHub Copilot (VS Code)
code-review-graph install --platform copilot-cli  # configure only GitHub Copilot CLI

Requires Python 3.10+. For the best experience, install uv (the MCP config will use uvx if available, otherwise falls back to the code-review-graph command directly).

Then open your project and ask your AI assistant:

Build the code review graph for this project

The initial build takes ~10 seconds for a 500-file project. After that, watch mode and supported hooks can keep the graph updated automatically.

Usage

<details> <summary><strong>Slash commands</strong></summary> <br>

</details>

<details> <summary><strong>CLI reference</strong></summary> <br>

code-review-graph install          # Auto-detect and configure all platforms
code-review-graph install --platform <name>  # Target a specific platform
code-review-graph build            # Parse entire codebase
code-review-graph update           # Incremental update (changed files only)
code-review-graph status           # Graph statistics
code-review-graph watch            # Auto-update on file changes
code-review-graph visualize        # Generate interactive HTML graph
code-review-graph visualize --format graphml   # Export as GraphML
code-review-graph visualize --format svg       # Export as SVG
code-review-graph visualize --format obsidian  # Export as Obsidian vault
code-review-graph visualize --format cypher    # Export as Neo4j Cypher
code-review-graph wiki             # Generate markdown wiki from communities
code-review-graph detect-changes --brief         # Risk panel + token savings (read-only)
code-review-graph update --brief                 # Refresh graph + same panel
code-review-graph detect-changes --brief --verify  # Cross-check vs tiktoken
code-review-graph register <path>  # Register repo in multi-repo registry
code-review-graph unregister <id>  # Remove repo from registry
code-review-graph repos            # List registered repositories
code-review-graph daemon start     # Start multi-repo watch daemon
code-review-graph daemon stop      # Stop the daemon
code-review-graph daemon status    # Show daemon status and repos
code-review-graph eval             # Run evaluation benchmarks
code-review-graph serve            # Start MCP server

</details>

<details> <summary><strong>Token Savings panel: <code>detect-changes --brief</code> vs <code>update --brief</code></strong></summary> <br>

Both commands print the same compact panel showing how many tokens the graph saved you compared to handing the changed files to an agent raw. They differ in one thing: whether the graph gets refreshed first.

┌─────────────────────── Token Savings ────────────────────────┐
│ Full context would be:     12,921 tokens                     │
│ Graph context used:           762 tokens                     │
│ Saved:                     12,159 tokens (~94%)              │
│ Breakdown: Functions 244 · Tests 191 · Risk 244 · Other 83   │
└──────────────────────────────────────────────────────────────┘

Both end with the same panel because both call the same analyze_changes() step at the end. The difference is whether the graph itself got refreshed before that analysis ran.

Add --verify to either command to cross-check the displayed numbers against OpenAI's cl100k_base tokenizer (the GPT-4 family). Requires pip install tiktoken. The estimate stays within ~1% of real tokens on a typical change set — see docs/REPRODUCING.md for the calibration data.

The same context_savings metadata is also attached automatically to the JSON responses of get_impact_radius, get_review_context, detect_changes, and get_architecture_overview MCP tools, so AI agents can surface the savings to humans in chat without any extra prompting.

</details>

<details> <summary><strong>Multi-repo daemon</strong></summary> <br>

If your editor doesn't support hooks (e.g. Cursor, OpenCode), or you just want your graph to stay fresh in the background without any editor integration, the daemon is for you. It watches your repos for file changes and automatically rebuilds the graph — no manual build or update commands needed.

The daemon is included with code-review-graph — no separate install required.

Quick setup:

```bash

Environment Variables

OpenAI-compatible embeddings (real OpenAI, Azure, or any self-hosted gateway like new-api / LiteLLM / vLLM / LocalAI / Ollama in openai mode) need no extra install — just set the environment variables and pass provider="openai" to embed_graph:

```bash export CRG_OPENAI_BASE_URL=http://127.0.0.1:3000/v1 # or https://api.openai.com/v1 export CRG_OPENAI_API_KEY=sk-... export CRG_OPENAI_MODEL=text-embedding-3-small # whatever your gateway serves

optional:

export CRG_OPENAI_DIMENSION=1536 # pin dim (v3 models support reduction) export CRG_OPENAI_BATCH_SIZE=100 # lower for gateways with tight limits # (e.g. Qwen text-embedding-v4 caps at 10)

The cloud-egress warning is auto-skipped when the base URL points to localhost
(`127.0.0.1`, `localhost`, `0.0.0.0`, `::1`).

> **Model selection tip.** Avoid `-preview` / `-beta` / `-exp` model IDs
> (e.g. `google/gemini-embedding-2-preview`) for anything you plan to keep
> long-term — preview models can change weights (different dimension → full
> re-embed required) or be deprecated without notice. Prefer stable GA
> releases such as `text-embedding-3-small` / `text-embedding-3-large` (OpenAI),
> `Qwen/Qwen3-Embedding-8B` (via self-hosted vLLM / LocalAI), or
> `gemini-embedding-001` (via the native Gemini provider, which requires
> `GOOGLE_API_KEY` instead of the OpenAI-compatible path).
>
> Also note: `code-review-graph` currently embeds **function signatures only**
> (~10 tokens per node, e.g. `"parse_file function (path: str) returns Tree"`).
> Models whose headline quality comes from long-context body understanding
> (such as Gemini 2 or Qwen3-8B at their MTEB-code SOTA scores) will see a
> much narrower quality gap against smaller models at this input length.
> Body/docstring embedding is tracked as a follow-up enhancement.

#### Tool Filtering

CRG exposes 30 MCP tools by default. In token-constrained environments, you can
limit the server to a subset of tools using `--tools` or the `CRG_TOOLS`
environment variable:

Via environment variable

CRG_TOOLS=query_graph_tool,semantic_search_nodes_tool code-review-graph serve

The CLI flag takes precedence over the environment variable. When neither is set,
all tools are available. This is especially useful for MCP client configurations:

</details>

---

Windows Configuration Issues (Invalid JSON / Connection Closed)

If you are using Windows and encounter Invalid JSON: EOF while parsing or MCP error -32000: Connection closed when connecting via Claude Code, do not use the cmd /c wrapper in your config.

Ensure fastmcp is updated to at least 3.2.4+. Then, configure your ~/.claude.json to execute the .exe directly and pass the UTF-8 environment variable via the config:

"code-review-graph": {
  "command": "C:\\path\\to\\your\\venv\\Scripts\\code-review-graph.exe",
  "args": ["serve", "--repo", "C:\\path\\to\\your\\project"],
  "env": { "PYTHONUTF8": "1" }
}

Via CLI flag

code-review-graph serve --tools query_graph_tool,semantic_search_nodes_tool,detect_changes_tool

Troubleshooting