code-review-graph

# code-review-graph > Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection. `code-review-graph` builds a persistent structural map of a codebase using Tree-sitter, stores it in a local SQLite graph, and exposes it to Claude via MCP. Instead of re-reading entire projects on every task, Claude queries the graph and reads only the files in the blast radius of a change — averaging 6.8× fewer tokens on code reviews and up to 49× on daily coding tasks in large monorepos. --- ## Installation ### Claude Code Plugin (recommended) ```bash claude plugin marketplace add tirth8205/code-review-graph claude plugin install code-review-graph@code-review-graph ``` Restart Claude Code after installation. ### pip ```bash pip install code-review-graph code-review-graph install # registers the MCP server with Claude Code ``` Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/). ### Optional: semantic search support ```bash pip install code-review-graph[embeddings] ``` Enables vector embeddings via `sentence-transformers` for `semantic_search_nodes_tool`. --- ## Initial Setup After installation, open your project in Claude Code and run: ``` Build the code review graph for this project ``` Or use the slash command: ``` /code-review-graph:build-graph ``` The first build parses the full codebase (~10 seconds for 500 files). After that, the graph updates incrementally on every file save and git commit (under 2 seconds for a 2,900-file project). --- ## CLI Reference ```bash # Register MCP server with Claude Code code-review-graph install # Parse entire codebase into the graph (first run) code-review-graph build # Re-parse only changed files (subsequent runs) code-review-graph update # Show graph statistics: node count, edge count, language breakdown code-review-graph status # Auto-update the graph as you save files (continuous watch mode) code-review-graph watch # Generate an interactive D3.js HTML visualisation of the graph code-review-graph visualize # Start the MCP server manually (Claude Code does this automatically) code-review-graph serve ``` --- ## Slash Commands in Claude Code | Command | What it does | |---|---| | `/code-review-graph:build-graph` | Build or rebuild the code graph from scratch | | `/code-review-graph:review-delta` | Review changes since the last commit | | `/code-review-graph:review-pr` | Full PR review with blast-radius analysis | --- ## MCP Tools (used automatically by Claude) Once the graph is built, Claude calls these tools without manual prompting: | Tool | Purpose | |---|---| | `build_or_update_graph_tool` | Build or incrementally update the graph | | `get_impact_radius_tool` | Find all files/functions affected by a change | | `get_review_context_tool` | Return a token-optimised structural summary for review | | `query_graph_tool` | Query callers, callees, tests, imports, inheritance | | `semantic_search_nodes_tool` | Search code entities by name or meaning | | `embed_graph_tool` | Compute vector embeddings for semantic search | | `list_graph_stats_tool` | Graph size and health statistics | | `get_docs_section_tool` | Retrieve documentation sections | | `find_large_functions_tool` | Find functions/classes over a line-count threshold | --- ## Configuration: Ignoring Paths Create `.code-review-graphignore` in the repository root: ``` generated/** *.generated.ts vendor/** node_modules/** dist/** __pycache__/** *.pyc migrations/** ``` The graph will skip these paths during build and update. --- ## Python API The graph can be queried programmatically for custom tooling or scripts. ### Build and update the graph ```python from code_review_graph import GraphBuilder builder = GraphBuilder(repo_path="/path/to/your/project") # Full build (first time) stats = builder.build() print(f"Nodes: {stats['nodes']}, Edges: {stats['edges']}") # Incremental update (subsequent runs — only parses changed files) update_stats = builder.update() print(f"Re-parsed: {update_stats['files_updated']} files") ``` ### Query the graph ```python from code_review_graph import GraphQuery query = GraphQuery(repo_path="/path/to/your/project") # Find all callers of a function callers = query.get_callers("authenticate_user") print(callers) # ['api/views.py::login_view', 'tests/test_auth.py::test_login'] # Find all callees (functions called by a function) callees = query.get_callees("process_payment") print(callees) # Find tests that cover a file tests = query.get_tests_for("payments/processor.py") print(tests) # Get inheritance chain for a class parents = query.get_inheritance("AdminUser") print(parents) # ['BaseUser', 'PermissionMixin'] ``` ### Blast-radius analysis ```python from code_review_graph import ImpactAnalyzer analyzer = ImpactAnalyzer(repo_path="/path/to/your/project") # What is affected if this file changes? impact = analyzer.get_impact_radius("auth/models.py") print(impact) # { # "direct_callers": ["api/views.py", "middleware/auth.py"], # "transitive_dependents": ["api/tests/test_views.py", "integration/test_flow.py"], # "test_files": ["tests/test_auth.py"], # "blast_radius_size": 7 # } # Multiple changed files (e.g., from a git diff) changed_files = ["auth/models.py", "payments/processor.py"] combined_impact = analyzer.get_impact_radius(changed_files) ``` ### Semantic search ```python from code_review_graph import SemanticSearch # Requires: pip install code-review-graph[embeddings] search = SemanticSearch(repo_path="/path/to/your/project") # Embed the graph (one-time, cached) search.embed() # Search for code entities by concept results = search.search("rate limiting middleware", top_k=5) for r in results: print(r["node"], r["file"], r["score"]) ``` ### Find large functions ```python from code_review_graph import GraphQuery query = GraphQuery(repo_path="/path/to/your/project") # Find functions/classes over 50 lines (good for refactoring targets) large = query.find_large_functions(threshold=50) for item in large: print(f"{item['name']} in {item['file']}: {item['lines']} lines") ``` --- ## Common Patterns ### Pattern: Review only what changed in the current branch ```bash # In Claude Code, after making changes: /code-review-graph:review-delta ``` Claude will: 1. Call `build_or_update_graph_tool` to sync the graph with your edits 2. Call `get_impact_radius_tool` on changed files 3. Call `get_review_context_tool` to get a compact structural summary 4. Review only the relevant ~15 files instead of the full codebase ### Pattern: Continuous watch during development ```bash # Terminal 1: keep the graph fresh as you code code-review-graph watch # Terminal 2: your normal development workflow ``` Any file save triggers an incremental re-parse of only that file and its dependents. ### Pattern: Pre-commit hook ```bash # .git/hooks/pre-commit #!/bin/sh code-review-graph update ``` Makes the graph always current before Claude sees a commit. ### Pattern: Visualise the dependency graph ```bash code-review-graph visualize # Opens an interactive D3.js force-directed graph in your browser # Toggle edge types: calls, imports, inheritance, test coverage # Search nodes by name ``` ### Pattern: Check graph health ```bash code-review-graph status # Example output: # Graph: .code-review-graph/graph.db # Nodes: 4,821 (functions: 2,103 | classes: 487 | files: 312) # Edges: 11,204 (calls: 7,891 | imports: 2,108 | inherits: 205 | tests: 1,000) # Languages: Python (180), TypeScript (98), JavaScript (34) # Last updated: 2026-03-26 01:22:11 (3 files changed) ``` --- ## Supported Languages Python, TypeScript, JavaScript, Vue, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, Solidity, C/C++ Each language has full Tree-sitter grammar support for: functions, classes, imports, call sites, inheritance chains, and test detection. --- ## Adding a New Language Edit `code_review_graph/parser.py`: ```python # 1. Add file extension mapping EXTENSION_TO_LANGUAGE = { # ... existing entries ... ".ex": "elixir", ".exs": "elixir", } # 2. Add AST node type mappings for the new language _CLASS_TYPES["elixir"] = {"defmodule"} _FUNCTION_TYPES["elixir"] = {"def", "defp"} _IMPORT_TYPES["elixir"] = {"alias", "import", "use", "require"} _CALL_TYPES["elixir"] = {"call"} ``` Then add a test fixture in `tests/fixtures/elixir/` and open a PR. --- ## Where the Graph Is Stored The graph is stored locally in `.code-review-graph/graph.db` (SQLite). There is no external database, no cloud dependency, and no data leaves your machine. Add it to `.gitignore` if you don't want it committed: ```bash echo ".code-review-graph/" >> .gitignore ``` Or commit it to share the pre-built graph with your team (saves the ~10-second initial build for each developer). --- ## Troubleshooting ### Graph is stale / not reflecting recent changes ```bash code-review-graph update # incremental re-parse of changed files # or, if something seems wrong: code-review-graph build # full rebuild from scratch ``` ### MCP server not connecting to Claude Code ```bash # Re-register the MCP server code-review-graph install # Verify it's registered claude mcp list ``` Then restart Claude Code. ### `uv` not found ```bash # Install uv (required by the MCP server runner) curl -LsSf https://astral.sh/uv/install.sh | sh # or pip install uv ``` ### Semantic search not working ```bash # Install the embeddings extra pip install "code-review-graph[embeddings]" # Compute embeddings (required once after install) code-review-graph embed # or call embed_graph_tool via Claude ``` ### A language isn't being parsed Check that the file extension is in `EXTENSION_TO_LANGUAGE` and the corresponding Tree-sitter grammar is installed. Run `code-review-graph status` to see which languages were detected in your project. ### Build is slow on first run Expected — Tree-sitter parses every file. A 500-file project takes ~10 seconds. All subsequent `update` calls complete in under 2 seconds because only changed files are re-parsed (detected via SHA-256 hash comparison). --- ## How the Token Reduction Works On every review or coding task: 1. **Graph query**: Claude calls `get_impact_radius_tool` with the changed files 2. **Blast-radius tracing**: the graph follows call edges, import edges, and test edges to find every affected node 3. **Compact summary**: `get_review_context_tool` returns a 156–207 token structural summary (callers, dependents, test coverage gaps, dependency chains) 4. **Targeted reading**: Claude reads only the ~15 files in the blast radius, not the full codebase In the Next.js monorepo (27,732 files): without the graph Claude reads ~739K tokens; with the graph it reads ~15K tokens — a 49× reduction.