tirth8205/code-review-graph

code‑review‑graph – a local code‑knowledge graph for AI‑assisted code reviews

What it is – A Python package that parses a repository with Tree‑sitter, stores the resulting abstract‑syntax‑tree information in a SQLite graph, and serves a tiny, relevance‑focused slice of that graph to any AI‑powered coding assistant that speaks the Model Context Protocol (MCP). The goal is to replace the naïve “read the whole codebase” approach with a blast‑radius query that returns only the files, functions and tests that could be affected by a change.

Why it matters – Large projects can contain hundreds of thousands of source tokens. Feeding that whole corpus to a LLM costs thousands of tokens per request and slows down the review loop. By answering the same question with a few thousand tokens (≈ 65× reduction on typical repos) the assistant can run faster, cheaper, and with less hallucination risk.

Core ideas

Step	What happens
Parse	The tool runs Tree‑sitter parsers for every supported language (Python, JS/TS, Go, Rust, Java, C/C++, … plus notebooks). It extracts nodes such as functions, classes, imports, call sites and test definitions and writes them as graph nodes and edges (calls, inheritance, import relationships).
Store	All nodes/edges live in a local SQLite database. Optional vector embeddings (sentence‑transformers, Gemini, MiniMax, Voyage AI, or any OpenAI‑compatible endpoint) are added for semantic search.
Update	A pre‑commit hook, a watch‑mode daemon, or a manual code-review-graph build command incrementally re‑parses only files whose SHA‑256 hash changed, then updates the affected sub‑graph.
Query	When an AI tool asks for review context, the MCP server runs a blast‑radius query: starting from the changed file(s) it walks call/import edges, adds dependent files and related tests, and returns the minimal set of source snippets plus a small amount of structural metadata.

---

Quick start (from the README)

pip install code-review-graph          # or pipx install
code-review-graph install              # auto‑detect your AI coding tools, write MCP entries, install hooks/skills
code-review-graph build                # initial parse of the repository

install detects a long list of supported platforms (Codex, Claude Code, Cursor, Zed, Continue, GitHub Copilot, Gemini CLI, etc.) and injects the appropriate MCP configuration so the assistant automatically uses the graph.

You can also uninstall cleanly:

code-review-graph uninstall --dry-run   # preview
code-review-graph uninstall --yes       # apply without prompting

---

Main features (as listed in the README)

• Incremental updates – only re‑parses changed files; a two‑file edit in a 3 k‑file repo takes ~2.5 s.
• Broad language coverage – 30+ languages plus Jupyter/Databricks notebooks; framework‑aware parsing for PHP/Laravel and Java/Spring.
• Framework‑aware edges – Laravel routes, Blade templates, Spring DI calls, WebFlux routes, Temporal workflows, etc.
• Blast‑radius analysis – returns the smallest set of files/functions/tests that could be impacted by a change.
• MCP‑compatible server – works with any assistant that understands the Model Context Protocol.
• GitHub Action – runs the same analysis in CI, posts a sticky PR comment with risk‑scored functions, and can block merges via fail-on-risk.
• Semantic search – optional vector embeddings from a variety of providers for richer keyword queries.
• Custom language support – add a languages.toml to map unknown extensions to an existing Tree‑sitter grammar.

---

Benchmarks (from the README)

• Token reduction – median ≈ 63× fewer tokens per question across six open‑source repos (fastapi, flask, etc.). The best case was 358×.
• Impact‑analysis quality – average F1 ≈ 0.69 against a graph‑derived ground truth (recall is 1.0 by construction, precision is deliberately lower to avoid missed dependencies).
• Build stats – a typical repo (≈ 6 k nodes, 30 k edges) builds in ~40 s on a clean checkout.

---

Limitations (as acknowledged)

• The “recall = 1.0” metric is circular because the ground truth is derived from the same graph.
• For tiny, single‑file edits the graph payload can be larger than just reading the file.
• Search ranking still needs improvement; some queries (e.g., Express modules) may return no hits.
• Flow detection is strongest for Python and PHP/Laravel; JavaScript and Go need work.
• The analysis is intentionally conservative, so precision can be low on large dependency graphs.

---

Who should use it?

• Developers who rely on LLM‑based code‑review assistants and want the assistant to see only the truly relevant parts of a large codebase.
• Teams that run AI‑assisted CI checks and need a deterministic, offline way to compute risk‑scored review context.
• Tool makers building new MCP‑compatible agents; they can plug the provided server into any editor or CLI.

---

Where to learn more

• Full usage guide: docs/USAGE.md
• Command reference: docs/COMMANDS.md
• GitHub Action details: docs/GITHUB_ACTION.md
• Benchmark reproduction steps: docs/REPRODUCING.md
• Community: Discord link in the badge bar, website at code‑review‑graph.com.

---

Bottom line – code‑review‑graph is a genuine, open‑source AI‑tooling project that builds a language‑aware, incrementally updated code graph and exposes it via MCP so LLM‑based reviewers can work with dramatically smaller, more precise context.