Setup

Better Code Review Graph – Manual Setup Guide

CLI-first (2026-09-13)

Repo is now n24q02m/crg. CLI-first: crg --help (config, doctor, graph, query, relay, review, security). PyPI package stays better-code-review-graph; both crg and legacy command work. MCP server is a secondary surface.

2026-05-02 Update: Plugin install (Method 1) now uses pure stdio mode. API keys are optional env vars. The previous “Zero-Config Relay” auto-spawn pattern has been removed. If you relied on the relay form to enter API keys, please:

Set the env var directly in plugin config (Method 1), OR

Use HTTP self-host mode (advanced; out of scope of this guide).

Method overview

This plugin defaults to stdio via plugin install (uvx) – the simplest path and the one this guide covers in full. Its source tree provides Docker stdio and http build targets, and it supports HTTP transport (MCP_TRANSPORT=http / TRANSPORT_MODE=http / --http) for operator-hosted deployments. It does not offer an owner-hosted remote-relay/OAuth endpoint – HTTP here is self-host only and must retain access to the repository being indexed.

For comparison, the other 7 plugins in this stack (better-notion-mcp, better-email-mcp, better-telegram-mcp, wet-mcp, mnemo-mcp, imagine-mcp, better-workspace-mcp) document 3 methods:

Default – Plugin install (uvx/npx) stdio
Fallback – Docker stdio (Windows/macOS PATH issues)
Recommended – Docker HTTP (multi-device, OAuth/relay form, claude.ai web)

⚠️ Mutually exclusive — pick ONE per plugin: Do NOT stack /plugin install AND a user mcpServers override (Docker stdio or HTTP) — both would load simultaneously and create duplicate entries (plugin’s npx/uvx stdio + your override). Plugin matching is by endpoint (URL or command string) per CC docs, not by name — and npx/uvx ≠ docker ≠ HTTP URL, so all three are distinct endpoints. Choosing the Docker stdio or HTTP self-host path means losing the plugin’s skills/agents/hooks/commands. For full plugin features, use the default plugin install (Method 1) documented below.

Prerequisites

Python 3.13 (3.14+ is NOT supported)
uv or uvx installed (docs)
Docker (optional, for containerized setup)
A code repository to analyze

Method 1: Claude Code Plugin (Recommended)

Plugin marketplace install runs the server in pure stdio mode with optional API key env vars. No daemon-bridge, no auto-spawn, no relay form. The graph is stored locally in SQLite, and local embeddings are resolved through Fastretrieval’s ONNX model registry – no external graph database required.

Credential prompts at install

When you run /plugin install, Claude Code prompts you for the following credentials (declared in userConfig per CC docs). Sensitive values are stored in your system keychain and persist across /plugin update:

Field	Required	Where to obtain
`JINA_AI_API_KEY`	Optional	https://jina.ai/api-key
`GEMINI_API_KEY`	Optional	https://aistudio.google.com/apikey
`OPENAI_API_KEY`	Optional	https://platform.openai.com/api-keys
`COHERE_API_KEY`	Optional	https://dashboard.cohere.com/api-keys
`EMBEDDING_MODELS` / `SUMMARY_MODELS`	Optional	Explicit cloud model selection; empty leaves local embeddings / disabled summaries
`LOCAL_EMBEDDING_MODEL` and its metadata fields	Optional	Built-in Fastretrieval ID, manifest-backed artifact directory, or external model with explicit dimensions
`LOCAL_RERANK_MODEL`	Optional	Fastretrieval `TextCrossEncoder` model ID; empty disables query reranking

Steps

Open Claude Code.

Install the plugin (skip optional model/key prompts to keep local embeddings):

/plugin marketplace add n24q02m/claude-plugins
/plugin install better-code-review-graph@n24q02m-plugins

The server starts automatically when Claude Code launches.
The SessionStart hook auto-builds the graph for the current project; PostToolUse updates it after edits.

Credential Setup

All API keys are optional. The server works with Fastretrieval’s local ONNX embedding registry out of the box.

Stdio Mode (Env Vars)

Set API keys in your MCP client env block or shell profile:

export EMBEDDING_MODELS="cohere/embed-v4.0"
export COHERE_API_KEY="<your-provider-key>"

For managed HTTP use, configure the authenticated subject’s model, API base, and key through the relay instead. See the managed provider policy before any paid calls.

Environment Variable Reference

Variable	Required	Default	Description
`JINA_AI_API_KEY`	No	–	Key for explicitly selected `jina_ai/` embedding models; not used by the managed Cloudflare route
`GEMINI_API_KEY`	No	–	Gemini: embedding (free tier). Also accepts `GOOGLE_API_KEY`
`GOOGLE_VERTEX_EXPRESS_API_KEY`	No	–	Vertex AI Express: Gemini via API key, no Service Account. Get it at https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview
`OPENAI_API_KEY`	No	–	OpenAI: embedding
`COHERE_API_KEY`	No	–	Key for explicitly selected `cohere/` embeddings; Cohere calls are paid
`EMBEDDING_MODELS`	No	empty	CSV embedding model selection (`provider/model,...`); the current runtime selects the first entry, not a fallback chain
`LOCAL_EMBEDDING_MODEL`	No	–	Optional BYO local embedding model ID; empty uses Fastretrieval’s bundled model manifest
`LOCAL_RERANK_MODEL`	No	–	Fastretrieval TextCrossEncoder model ID; empty = reranking disabled.
`LOCAL_EMBEDDING_MODEL_FILE`	No	`onnx/model.onnx`	ONNX file path for a BYO local embedding
`LOCAL_EMBEDDING_DIM`	No	`0`	Required for a BYO local embedding when its model manifest does not provide dimensions
`LOCAL_EMBEDDING_POOLING`	No	`MEAN`	Pooling for a BYO local embedding (`MEAN`, `CLS`, `LAST_TOKEN`, or `DISABLED`)
`LOCAL_EMBEDDING_NORMALIZE`	No	`true`	Normalize BYO local embedding outputs
`LOCAL_RERANK_MODEL`	No	empty	Fastretrieval `TextCrossEncoder` model ID for query reranking; empty disables reranking
`SUMMARY_MODELS`	No	empty	Ordered CSV summary model chain (`provider/model,...`); empty leaves summaries disabled
`EMBEDDING_API_BASE`	No	–	Provider-compatible embedding endpoint or CF AI Gateway embedding URL; SSRF-guarded
`LLM_API_BASE`	No	–	Provider-compatible completion base URL or CF AI Gateway OpenRouter route; SSRF-guarded
`OPENROUTER_API_KEY`	No	–	Credential for explicitly selected `openrouter/` completion models
`HULL_EMBED_API_KEY`	No	–	Host-injected key for the `[models.embed]` cell transport (OpenRouter pre-wired default); overrides the cell `api_key`. The model name still comes from `EMBEDDING_MODELS`
`HULL_CHAT_API_KEY`	No	–	Host-injected key for the `[models.chat]` cell transport (OpenRouter pre-wired default); enables LLM summaries when the cell model is set

Embedding provider selection

Cloud: a non-empty EMBEDDING_MODELS value selects its first provider/model; later entries are not runtime fallbacks.
Local: an empty chain resolves Fastretrieval’s local ONNX model registry/manifest; set LOCAL_EMBEDDING_MODEL only for a BYO local model.
Custom local metadata: a BYO model can use LOCAL_EMBEDDING_MODEL_FILE, LOCAL_EMBEDDING_DIM, LOCAL_EMBEDDING_POOLING, and LOCAL_EMBEDDING_NORMALIZE; manifest-backed models supply their own metadata.
Legacy aliases: EMBEDDING_BACKEND and EMBEDDING_MODEL are deprecated and honored for one release; migrate to EMBEDDING_MODELS.

Embeddings are tagged with the active provider/model identity. Cohere embed-v4.0 requests and stores exactly 1024 dimensions; other backends retain 768-dimensional storage. CRG does not slice or pad provider vectors. Run graph(action="embed") after changing models or upgrading an older 768-wide Cohere index. Document embeddings use search_document; queries use search_query, and incompatible stored widths require re-embedding.

Query reranking is local and opt-in through LOCAL_RERANK_MODEL. CRG does not currently implement RERANK_MODELS, RERANK_API_BASE, or a cloud reranking provider. A Cohere embedding selection does not enable Cohere reranking.

Graph-state migration

Local graph, security scan cache, and suppression state use the package-owned .better-code-review-graph/ directory. After upgrading, run graph(action="build", full_rebuild=true), then graph(action="embed") if semantic search is needed. The old .code-review-graph/, .code-review-graph.db, and SQLite sidecars are left untouched because they may belong to the separate upstream package. Review and reapply desired suppression rules explicitly rather than deleting or adopting that state automatically.

Supported Languages

Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C/C++, Solidity

Ignore Files

Create .code-review-graphignore in your project root to exclude paths:

generated/**
*.generated.ts
vendor/**
node_modules/**

Troubleshooting

Graph build finds no files

Ensure the repo_path parameter points to the root of a code repository. Check that the project contains files in a supported language.

First embedding is slow

On first use, Fastretrieval’s local ONNX embedding model (~570MB) is downloaded. Subsequent runs are instant. Use a configured cloud embedding chain to avoid this download.

“No graph found” error

Build the graph first:

graph(action="build", repo_path="/path/to/your/repo")

Docker cannot access repo files

Build the stdio target from a reviewed release tag, then verify the volume mount. The repo path inside the container is /repo:

git clone --branch <release-tag> --depth 1 https://github.com/n24q02m/crg.git
cd better-code-review-graph
docker build --target stdio -t better-code-review-graph:local .
docker run -i --rm -v "/absolute/path/to/repo:/repo:ro" better-code-review-graph:local