code-review-graph
CLI Tooltirth8205/code-review-graph
Local-first code intelligence graph for AI code review via MCP and CLI.
Overview
Builds a persistent structural map of your codebase using Tree-sitter. Tracks changes incrementally and provides precise context to AI coding tools via MCP. Reduces token usage in code reviews significantly.
README Preview
code-review-graph\n\n\n Stop burning tokens. Start reviewing smarter.\n\n\n\n English |\n 简体中文 |\n 日本語 |\n 한국어 |\n हिन्दी\n\n\n\n \n \n \n \n \n \n \n \n \n\n\n\n Usage ·\n Commands ·\n FAQ ·\n Troubleshooting ·\n GitHub Action ·\n Reproducing the benchmarks ·\n Roadmap\n\n\n\n\nAI coding tools can end up re-reading large parts of your codebase on review tasks. `code-review-graph` fixes that. It builds a structural map of your code with [Tree-sitter](https://tree-sitter.github.io/tree-sitter/), tracks changes incrementally, and gives your AI assistant precise context via [MCP](https://modelcontextprotocol.io/) so it reads only what matters.\n\n\n \n\n\n---\n\n## Quick Start\n\n```bash\npip install code-review-graph # or: pipx install code-review-graph\ncode-review-graph install # auto-detects and configures all supported platforms\ncode-review-graph build # parse your codebase\n```\n\nOne 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.\n\n\n \n\n\nTo target a specific platform:\n\n```bash\ncode-review-graph install --platform codex # configure only Codex\ncode-review-graph install --platform cursor # configure only Cursor\ncode-review-graph install --platform claude-code # configure only Claude Code\ncode-review-graph install --platform gemini-cli # configure only Gemini CLI\ncode-review-graph install --platform kiro # configure only Kiro\ncode-review-graph install --platform copilot # configure only GitHub Copilot (VS Code)\ncode-review-graph install --platform copilot-cli # configure only GitHub Copilot CLI\ncode-review-graph install --platfo
FAQ (5)
TroubleshootingWhy does code-review-graph report Java @Override methods and JUnit @BeforeEach lifecycle methods as dead code?
In code-review-graph 2.3.8, _FRAMEWORK_DECORATOR_PATTERNS in flows.py does not recognize Java's @Override or JUnit/TestNG lifecycle annotations, so methods invoked by the JDK contract or test runner are incorrectly classified as dead.
Apply the fix from #1034, or manually add these patterns to _FRAMEWORK_DECORATOR_PATTERNS in flows.py:
re.compile(r"^Override$"),
re.compile(
r"^(Test|Before|After|BeforeEach|AfterEach|BeforeAll|AfterAll"
r"|BeforeClass|AfterClass|ParameterizedTest|RepeatedTest|TestFactory)$"
),
Then rebuild and rerun:
code-review-graph build --repo . --data-dir /tmp/dc-data
code-review-graph dead-code --repo . --data-dir /tmp/dc-data
The anchored Override pattern prevents unrelated annotations such as override_settings from matching. After the patch, hashCode() and @BeforeEach setUp() are no longer reported, while genuinely unused symbols remain flagged.
TroubleshootingWhy do non-ASCII source files appear as mojibake in code review snippets on Windows, and how do I fix it?
The files are being decoded with the Windows system locale encoding (usually cp1252) instead of UTF-8. Fix each open() call by explicitly passing encoding="utf-8"; keep errors="replace" only where partial output is preferred:
with open(path, encoding="utf-8", errors="replace") as f:
source = f.read()
Apply this to tools/review.py, tools/flows_tools.py, context_savings.py, token_benchmark.py, eval/runner.py, and eval/reporter.py. The upstream fix is in PR #928, folded into #988 and merge 3030ca8; it will be included in the next release. As a temporary workaround on Windows, enable Python UTF-8 mode before running the tool:
set PYTHONUTF8=1
PowerShell:
$env:PYTHONUTF8 = "1"TroubleshootingHow do I fix duplicated nodes when code-review-graph build rebuilds a pre-2.3.8 Windows graph?
This affects code-review-graph 2.3.8 on Windows. The stale-file purge selects old rows using their stored backslash paths, but normalizes them to POSIX paths before deletion, so nothing is deleted and the build inserts every node again.
Fix: upgrade to a release containing PR #988 (the fix was merged to staging and targeted for the release after 2.3.8), then rerun:
code-review-graph build --repo . --data-dir <your-data-dir>
The fixed build removes legacy rows using their exact stored spelling while preserving canonical POSIX rows.
If you cannot upgrade yet, rebuild into a fresh data directory instead of reusing the old one:
code-review-graph build --repo . --data-dir C:/tmp/graph-fresh
Verify the new database, then point your tooling at it or replace the old data directory. A successful exit code and normal Full build log line do not prove that duplication was avoided in 2.3.8.
TroubleshootingHow do I fix `code-review-graph tests_for` returning 0 results for Python code that has tests and `TESTED_BY` edges?
This is a bug in code-review-graph 2.3.8. Python TESTED_BY edges may use a bare symbol name, while tests_for looks up a fully qualified path such as /abs/path/file.py::Class.method. The fallback compares absolute file paths against dotted Python module names like odoo.addons.module.file, so the import-evidence check fails and covered code is reported as uncovered.
Immediate workaround: use callers_of and identify callers marked is_test=True:
code-review-graph query callers_of "/abs/path/wizard_update_invoice_supplierinfo_line.py::WizardUpdateInvoiceSupplierinfoLine._prepare_supplierinfo_update"
Permanent fix: upgrade to a release containing the Python import-resolution fixes from PR #960/#988 and PR #997. If building from source, use a build that includes commits 3030ca8 and 9c13f4c, or build from staging until the fix is merged into main. The fix resolves dotted Python modules to their repository files before comparing import evidence, allowing the bare-name fallback to find the existing TESTED_BY edge.
TroubleshootingHow do I stop the code-review-graph pre-commit hook from creating a separate graph database in a git worktree?
This happens in code-review-graph 2.3.8 because the installed hook runs code-review-graph update without --repo. From a linked worktree, repository discovery resolves to that worktree and creates a new .code-review-graph database.
A fix is available on staging via PR #988 (merge 3030ca8) and will ship in the next release. The corrected hook passes --repo and skips automatic graph checks in linked worktrees unless CRG_HOOK_WORKTREES=1 is set. After upgrading, reinstall the hook:
code-review-graph install
Immediate workaround for 2.3.8:
1. Open the shared hook:
$(git rev-parse --git-path hooks/pre-commit)
2. Make it skip linked worktrees and explicitly target the main checkout:
#!/bin/sh
if command -v code-review-graph >/dev/null 2>&1; then
if [ "$(git rev-parse --git-dir)" = "$(git rev-parse --git-common-dir)" ]; then
code-review-graph update --repo /absolute/path/to/main-checkout || true
code-review-graph detect-changes --brief --repo /absolute/path/to/main-checkout || true
fi
fi
3. Remove databases already created inside worktrees:
rm -rf /path/to/worktree/.code-review-graph
As a one-off alternative, commit in the worktree with git commit --no-verify, then run code-review-graph update from the main working tree.