code review graph - Moses Yebei

Abstract

Local knowledge graph for Claude Code. Builds a persistent map of your codebase so Claude reads only what matters — 6.8× fewer tokens on reviews and up to 49× on daily coding tasks.

code-review-graph Technical Briefing

The Problem

AI coding tools re-read entire codebases on every task, burning tokens unnecessarily. This repo addresses that by building a persistent structural map so assistants read only what matters. The README states 6.8× fewer tokens on reviews and up to 49× on daily coding tasks.

What This Does

code-review-graph uses tree-sitter to parse code structure and tracks changes incrementally. The core graph lives in code_review_graph/graph.py (63 functions, 5 classes, called from 52 other files), while code_review_graph/parser.py (80 functions, 4 classes) handles language-specific parsing. Incremental updates are managed by code_review_graph/incremental.py (35 functions, 2 classes). The system exposes MCP-compatible tools via code_review_graph/main.py — get_minimal_context_tool (line 158, reaches 42 functions) and get_review_context_tool (line 240, reaches 30 functions) are the primary entry points for AI assistant integration. The VS Code extension in code-review-graph-vscode/ provides the UI layer, with src/backend/cli.ts as its entry point.

How It Is Wired

Execution starts at the CLI: code_review_graph/cli.py:315 (main) reaches 280 functions and is called from 4 places. The import graph has 121 modules and 277 edges with zero circular dependencies. The most connected module is code_review_graph/graph (54 importers, 3 imports, instability 0.05), while code_review_graph/tools/__init__ has high instability at 0.72 (5 importers, 13 imports).

Traced paths to external effects: main -> get_db_path triggers filesystem deletion via side.unlink; get_minimal_context_tool -> get_minimal_context -> _has_git_changes runs subprocess.run; get_review_context_tool -> get_review_context reads files via full_path.read_text. The call graph contains 2,585 resolved edges — commit is called from 78 places, NodeInfo from 60, parse_file from 55.

How To Use It

Setup: pip install code-review-graph (or pipx). Then code-review-graph install auto-detects platforms and writes MCP configuration. Supported via --platform cursor, --platform claude-code, or --platform kiro. Requires Python 3.10+; uv is recommended for uvx integration.

Build: code-review-graph parse constructs the graph. Initial build takes ~10 seconds for a 500-file project; subsequent updates happen automatically on file edits and git commits.

Real-World Use

After code-review-graph install, open your project and invoke: Build the code review graph for this project. The assistant then uses get_minimal_context_tool to retrieve only relevant code — the graph ensures it reads ~6.8× fewer tokens during reviews. On daily coding tasks, context is further reduced, keeping the AI focused on the modified area.

Code Health & Issues

Static analysis of 122 code files identified these findings:

[MEDIUM] Broad exception handling x7 — code_review_graph/graph.py, code_review_graph/communities.py, code_review_graph/embeddings.py: Bare except clauses swallow errors indiscriminately.
[HIGH/cognitive_load] Deep nesting x35 — code_review_graph/graph.py, code_review_graph/parser.py, code_review_graph/incremental.py: Max indentation depth 7; control flow is hard to follow. Fix: flatten with guard clauses.
[HIGH/cognitive_load] Oversized file x12 — Same files: 1,156-line files ripple changes widely. Fix: split into cohesive units.
[HIGH/clarity] Hub module x5 — code_review_graph/graph.py is depended on by 54 modules; churn here has high-blast-radius. Fix: keep stable and small; move volatile logic out.
[HIGH/clarity] Duplicated code blocks — 2,027 repeated 6-line blocks across 60 files in code-review-graph-vscode/. Extract shared helpers.

Repository hygiene findings: no Dependabot/Renovate configured, no dependency vulnerability scan in CI, checkout retains token (persist-credentials not disabled), two workflow jobs lack timeouts, and convention files (.editorconfig, .gitattributes) are absent.

The Bottom Line

The graph construction and incremental update logic work well — the token reduction claim is credible given the module mapping and call-graph analysis. However, the codebase shows significant maintainability risk: three files carry most import and call traffic, deep nesting is prevalent, and exception handling is broad. The hygiene gaps (no update bot, no dependency scanning) are easy to remediate. This is worth adopting if you control the AI assistant pipeline and want to reduce token consumption, but plan to allocate engineering time to restructure the high-traffic modules.

Word count: ~480

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

261 files

Python109
Markdown40
TypeScript25
YAML10
JSON7
Shell5

ReactVueFlaskFastAPIExpressSpark

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["code_review_graph<br/>66 modules"] g1["tests<br/>35 modules"] g2["code-review-graph-vsco<br/>19 modules"] g1 -->|105| g0

Module dependencies

The 10 most depended-upon modules of 121, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_code_review_graph_graph["graph"] n1_code_review_graph_parser["parser"] n2_ode_review_graph_incremental["incremental"] n3_code_review_graph_search["search"] n4_code_review_graph_flows["flows"] n5_ode_review_graph_communities["communities"] n6_ph_vscode_src_backend_sqlite["sqlite"] n7_e_review_graph_tools__common["_common"] n8_code_review_graph_changes["changes"] n9_code_review_graph_hints["hints"] n8_code_review_graph_changes --> n4_code_review_graph_flows n8_code_review_graph_changes --> n0_code_review_graph_graph n5_ode_review_graph_communities --> n0_code_review_graph_graph n4_code_review_graph_flows --> n0_code_review_graph_graph n0_code_review_graph_graph --> n1_code_review_graph_parser n2_ode_review_graph_incremental --> n0_code_review_graph_graph n2_ode_review_graph_incremental --> n1_code_review_graph_parser n3_code_review_graph_search --> n0_code_review_graph_graph n7_e_review_graph_tools__common --> n0_code_review_graph_graph n7_e_review_graph_tools__common --> n2_ode_review_graph_incremental

Dependencies

9 of 17 declared dependencies are a major version behind. Resolved 17 of 17 against the registry.

Package	Declared	Latest	Behind
`@types/node`	^20.11.0	26.2.0	6 major
`@types/better-sqlite3`	^7.6.13	9.6.0	2 major
`typescript`	^5.3.3	7.0.2	2 major
`watchdog`	>=4.0.0,<6	6.0.0	2 major
`better-sqlite3`	^12.4.1	13.0.3	1 major
`@vscode/test-electron`	^2.3.8	3.1.0	1 major
`@vscode/vsce`	^2.22.0	3.9.2	1 major
`mcp`	>=1.0.0,<2	2.0.0	1 major

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

medium3

low2

Enable Dependabot or Renovatemedium

2 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow2 occurrences

.github/workflows/ci.yml

2 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.