Setup

Better Code Review Graph – Manual Setup Guide

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:

1. Set the env var directly in plugin config (Method 1), OR
2. 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:

1. Default – Plugin install (uvx/npx) stdio
2. Fallback – Docker stdio (Windows/macOS PATH issues)
3. 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

Steps

1. Open Claude Code.
2. Install the plugin (Claude Code prompts for JINA_AI_API_KEY – press Enter to skip):

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

3. The server starts automatically when Claude Code launches.
4. 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 JINA_AI_API_KEY="jina_..."
export GEMINI_API_KEY="AIza..."

Environment Variable Reference

Variable	Required	Default	Description
JINA_AI_API_KEY	No	–	Jina AI: embedding + reranking (highest priority)
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	–	Cohere: embedding + reranking. Also accepts CO_API_KEY
EMBEDDING_MODELS	No	empty	Ordered CSV embedding model chain (provider/model,...); empty resolves Fastretrieval’s local ONNX model manifest
EMBEDDING_DIMS	No	0 (auto)	Embedding dimensions; custom local models may require LOCAL_EMBEDDING_DIM
LOCAL_EMBEDDING_MODEL	No	–	Optional BYO local embedding model ID; empty uses Fastretrieval’s bundled model manifest
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
SUMMARY_MODELS	No	empty	Ordered CSV summary model chain (provider/model,...); empty leaves summaries disabled

| TRANSPORT_MODE | No | stdio | Set to http to enable HTTP transport (multi-user). | | PUBLIC_URL | Yes (http) | – | Server’s public URL for relay form. | | MCP_DCR_SERVER_SECRET | Yes (http) | – | HMAC secret for stateless Dynamic Client Registration. | | MCP_PORT | No | 8080 | Server port (http mode only). | | LOG_LEVEL | No | INFO | Logging level | Legacy aliases: EMBEDDING_BACKEND, EMBEDDING_MODEL, and SUMMARY_MODEL are deprecated and honored for one release. Use EMBEDDING_MODELS and SUMMARY_MODELS instead.

Embedding provider selection

• Cloud: a non-empty EMBEDDING_MODELS chain selects the first configured provider/model, with later entries as fallback.
• 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.

All embeddings are stored at a fixed dimension and tagged with the active provider/model identity. Changing the provider/model or dimensions changes the vector space: affected nodes are re-embedded, and semantic search uses the active provider/model vectors.

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/better-code-review-graph.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