code-review-graph

What you will run into

AI code review either looks at too much or misses things. code-review-graph builds a local knowledge graph of your codebase (tree-sitter parsing, SQLite stored in the workspace's .code-review-graph/), so the AI only reviews relevant code — change one function and it tells you which files the change affects. When to use it:

• Giving AI reviews "impact surface" context (changing A affects B);
• Running build to build the graph, watch for incremental watching, status for stats inside a codebase;
• Registering the graph as an MCP server for Claude/Codex/Cursor (install).

When not to use it: small repos, single-file changes, where the graph costs more than it saves. Notes: multi-registration heavyweight — install registers MCP/hooks with detected platforms (writes ~/.claude.json, ~/.codex/hooks.json etc.); the official uninstall cleans everything up.

Path: Quick fix (30s, one command) -> Step by step (skimmable) -> How to confirm it works (success criteria). In a hurry? Jump to Quick fix.

Why this happens

CLI installed via pip (pipx also possible, officially recommended, not verified here). Inside a workspace (git repo), build builds the full graph (tree-sitter parse → SQLite), watch incrementally watches file changes (background crg-daemon), status shows stats, detect-changes read-only analyzes change impact (change A → know B). install registers an MCP server with detected platforms (multi-platform write surface, see dependency warnings). build/status/detect-changes/watch verified on an isolated repo (2026-08-30). Key concepts:

• Graph data: workspace .code-review-graph/ (SQLite);
• crg-daemon: the background process in watch mode;
• MCP registration: the multi-platform config sections install writes.

Where it writes: the pip environment + workspace .code-review-graph/; after install: ~/.claude.json (mcpServers), ~/.codex/hooks.json, ~/.cursor/mcp.json, ~/.config/opencode/plugins/crg-plugin.ts, workspace .claude/settings.json and .mcp.json.

Step by step

Step 1: Install the CLI (why pin the version: 2.3.8 is the verified collection version)

Why: PyPI official direct times out in this environment (probe 2026-08-27), so the Tsinghua mirror prefix is required; pinning 2.3.8 keeps everything consistent with what was verified. Verify with --version after install.

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple code-review-graph==2.3.8
code-review-graph --version

Expected output: code-review-graph 2.3.8 After install, confirm:

• --version prints 2.3.8;
• inside a git repo, code-review-graph --help shows build/status/watch/install subcommands.

Stuck? How to recover:

• pip won't install → confirm Python >= 3.10; retry with the Tsinghua mirror prefix;
• command not found → activate the venv in venv scenarios first.

Step 2: Build the graph + view stats (core usage, run inside the target repo)

Why: build parses the full codebase to generate the graph (first run is slower, normal); status shows node/edge/file stats. After this, AI reviews can use the graph to locate impact surfaces.

code-review-graph build

Expected output: parse progress + stats (verified sample: Full build: 5 files, 9 nodes, 16 edges; workspace gets .code-review-graph/graph.db)

code-review-graph status

Expected output: node/edge/file stats (verified sample: Nodes: 9 / Edges: 16 / Files: 5 / Languages: javascript, python / Built at commit: …) After install, confirm:

• after build, .code-review-graph/ contains graph data;
• status prints node/edge stats.

Stuck? How to recover:

• build is slow → first full parse is normal; use watch/update for incremental later;
• non-git repo → verified build/status do NOT error (2026-08-30) but cross-file references are not resolved (sample: 1 file → 0 edges); impact analysis is meaningless; cd to a git repo root for a full graph.

Step 3: Incremental watching + register MCP (optional)

Why: watch watches file changes for incremental updates (background crg-daemon, Ctrl+C to exit; verified 2026-08-30: ~2s auto update after a file change); detect-changes read-only analyzes the impact of current uncommitted changes (change A → know B, no rebuild needed); install registers an MCP server with detected platforms — this writes multi-platform config, so decide whether you want all-platform registration before installing.

code-review-graph watch

Expected output: Watching … for changes… (Ctrl+C to stop) (verified: file change triggers incremental update in ~2s; node/edge counts rise)

code-review-graph install

Expected output: registers an MCP server with detected platforms (writes ~/.claude.json, ~/.codex/hooks.json etc.) After install, confirm:

• watch mode logs file changes;
• after install, the corresponding platform config shows a code-review-graph section (~/.claude.json mcpServers etc.).

Stuck? How to recover:

• platform does not recognize after install → check the corresponding platform config files (~/.claude.json / ~/.codex/hooks.json / ~/.cursor/mcp.json / ~/.config/opencode/plugins/crg-plugin.ts);
• do not want all-platform registration → skip install, use only build/status/watch (CLI surface).

How to confirm it works

Step 1: Confirm the graph exists

Why: after build, the workspace has a .code-review-graph/ directory (SQLite graph data) — the most direct proof that "the graph was built".

ls -d .code-review-graph 2>/dev/null && echo "graph dir: OK" || echo "graph dir: MISSING"
code-review-graph status

Expected output: graph dir: OK plus node/edge/file stats Stuck? How to recover:

• directory missing → rerun build from "Step by step" step 2, confirm you are in a git repo root;
• status errors → check whether the current directory has graph data (running status elsewhere reads no graph for this repo).

Step 2: Confirm the AI can actually use it (if you registered MCP)

Why: after install, check that the corresponding platform config shows a code-review-graph section — the agent-side hookup is in place.

grep -l "code-review-graph" ~/.claude.json ~/.codex/hooks.json ~/.cursor/mcp.json 2>/dev/null || echo "check config files manually"

Expected output: at least one config file path (platforms with registration); none means not registered Stuck? How to recover:

• not in platform config → rerun install, confirm the platform is detected;
• CLI-only is fine → skip install; build/status/watch are already enough.

Other environments

• Non-git repos: verified build/status do NOT error (2026-08-30), but cross-file references are not resolved (sample: 1 file → 0 edges) — impact analysis is meaningless; still recommended to run at a git repo root for a full graph.
• Windows / macOS: same pip install commands (Tsinghua mirror still recommended); MCP config paths differ from Linux (on Windows ~/.claude.json is in the user dir, .cursor config under %USERPROFILE%); uninstall cleanup logic is the same.
• venv / conda: if the command is not found after install, activate the virtualenv first; pipx install is the officially recommended path (not verified here, command surface identical to pip).
• First build time: the bigger the repo, the slower the first build — normal; use watch/update for incremental afterwards.

Daily usage

Startup and entry

Call the CLI inside the target repo; watch mode listens in the background.

Common operations

Operation 1: Build the code graph

code-review-graph build

Expected output: parse progress + stats (verified sample: Full build: 5 files, 9 nodes, 16 edges; workspace gets .code-review-graph/graph.db) Operation 2: View graph stats

code-review-graph status

Expected output: node/edge/file stats (verified sample: Nodes: 9 / Edges: 16 / Files: 5 / Languages: javascript, python / Built at commit: …) Operation 3: Incremental updates (watch file changes)

code-review-graph watch

Expected output: Watching … for changes… (Ctrl+C to stop) (verified: file change triggers incremental update in ~2s; node/edge counts rise) Operation 4: Analyze change impact (read-only, run anytime after edits) Why: detect-changes does not re-parse; it read-only analyzes which functions/files your current uncommitted changes affect (JSON output: impacted list + risk_score + context savings estimate). Verified on a 5-file sample repo (2026-08-30).

code-review-graph detect-changes

Expected output: JSON impact report (affected functions/files + risk_score fields) Operation 5: Register MCP (multi-platform)

code-review-graph install

Expected output: registers an MCP server with detected platforms (writes ~/.claude.json, ~/.codex/hooks.json etc.)

Data and directories

• Graph data: workspace .code-review-graph/ (SQLite; confirm whether you need a backup before uninstall);
• Registration surface: ~/.claude.json (mcpServers), ~/.codex/hooks.json, ~/.cursor/mcp.json, ~/.config/opencode/plugins/crg-plugin.ts, workspace .claude/settings.json and .mcp.json.

Uninstall & cleanup

note: the official uninstall subcommand cleans up completely (data/config/hooks/skills/MCP registration), then uninstall the pip package; this marketplace one-click uninstall runs it automatically

code-review-graph uninstall 2>/dev/null || true
pip uninstall -y code-review-graph
command -v code-review-graph >/dev/null 2>&1 && echo "残留: code-review-graph 仍存在" || echo "code-review-graph removed: OK"

Expected output: code-review-graph removed: OK Manual checklist (for full cleanup):

• workspace .code-review-graph/ (graph data, confirm whether you need a backup before uninstall)
• the code-review-graph mcpServers section in ~/.claude.json (the official uninstall should clear it; delete manually if residue)
• ~/.codex/hooks.json / ~/.cursor/mcp.json / ~/.config/opencode/plugins/crg-plugin.ts (same)

Dependency warnings

• Version: [2.3.8, 2.3.8] locked (verified collection version).
• Environment: Python >= 3.10; graph building depends on repo structure (run inside a git repo).
• Network: PyPI official times out (probe 2026-08-27), must use the Tsinghua mirror.
• Write surface (multi): workspace .code-review-graph/ + post-install multi-platform registration sections (~/.claude.json / ~/.codex/hooks.json / ~/.cursor/mcp.json / ~/.config/opencode/plugins/crg-plugin.ts / workspace .claude/settings.json and .mcp.json).
• Co-install: with ruflo / omc / agt judged possible-conflict (same-file write surface on ~/.claude.json or workspace .claude/settings.json/.mcp.json, different keys/sections, co-install not tested); with deepcode / superpowers / claude-code-router judged possible-compatible.

FAQ

• Q: What does install change in my config? A: registers MCP/hooks with detected platforms: ~/.claude.json (mcpServers), ~/.codex/hooks.json, ~/.cursor/mcp.json, ~/.config/opencode/plugins/crg-plugin.ts, workspace .claude/settings.json and .mcp.json — all cleanable by the official uninstall.
• Q: Conflicts with ruflo/omc/agt installed together? A: judged possible-conflict — same-file write surface on ~/.claude.json or workspace .claude/settings.json/.mcp.json (different keys/sections), co-install not tested; install one and get it working first.
• Q: Build is slow? A: the first full build parse is normal; use watch/update for incremental afterwards.
• Q: Can't pip install domestically? A: use the Tsinghua mirror prefix from the install section (PyPI official times out in this environment).
• Q: Where to report usage problems? A: install/uninstall issues on this marketplace go through the entry feedback channel (usage-report template); project issues go to the author's repository.