code-review-graph

Files (1)

• SKILL.md

SKILL.md (first lines)

# Code Review Graph — Token-Efficient Codebase Context via MCP

> Cut AI token usage substantially on large codebases by giving the AI a structural map instead of letting it read everything. Savings scale with codebase size — marginal on small projects, large on monorepos.

## Overview

`code-review-graph` is an MCP server that uses **Tree-sitter** to parse your codebase into an AST graph stored in **SQLite**. When your AI assistant needs context for a task, it queries the graph first — getting only the files in the **blast radius** of your change — instead of reading every file in the directory.

**Token Impact (illustrative — varies by codebase):**

| Codebase Type | Pattern |
|---------------|---------|
| Large monorepo (10K+ files) | Biggest savings — graph reads a small fraction of files |
| Mid-size app (1-5K files) | Meaningful reduction on multi-file changes |
| Small project (<200 files) | Little benefit — graph overhead can exceed savings |

> **Quality angle:** scoping the AI to the blast radius reduces noise, which tends to improve review focus. Measure on your own repo rather than relying on a fixed multiplier.

## Bootstrap Protocol (opt-in)

When invoked during `/plan` or standard usage on a mid-to-large project, check whether graph analysis is available before relying on it:
1. **Step 1:** Check if the tool is installed: `Get-Command code-review-graph` (Windows) or `which code-review-graph` (macOS/Linux).
2. **Step 2:** Check if a `.code-review-graph/` directory exists in the workspace.
3. **Step 3:** If installed but the index is missing, ask the user before running `code-review-graph build` (it scans the whole project).
4. **Step 4:** If not installed and the project is large, ask the user: "Would you like to `pip install code-review-graph` and build a local map to cut token usage for this project?" Never install or run build without confirmation.

---

## When to Use vs When to Skip

### ✅ Install it if:
- Codebase is **500+ files**
- You make **multi-file changes** with cross-module dependencies
- You spend **$20+/month** on AI assistant tokens
- You work with **monorepos**, microservices, or cross-package TypeScript
- You want **better review quality** in addition to cost savings

### ❌ Skip it if:
- Codebase is **under ~200 files** with isolated single-file changes
- Heavy use of **dynamic patterns** (reflection, runtime code gen, dynamic imports)
- You want **zero-maintenance** — the graph needs to stay in sync
- Team hasn't standardized on an AI coding tool yet

### ⚠️ Evaluate first if:
- Codebase is **200–500 files** — benchmark before committing
- Mix of **static and dynamic patterns** — test on representative commits

---

## How It Works (4 Layers)

```
Layer 1: PARSE    → Tree-sitter builds ASTs from 19 languages
Layer 2: STORE    → Nodes + edges saved in SQLite graph
Layer 3: TRACE    → BFS computes blast radius of changes
Layer 4: SERVE    → MCP exposes graph to AI assistants
```

### What the Graph Contains
- **Nodes:** Files, functions, methods, classes, imports, tests
- **Edges:** "A calls B", "X imports Y", "TestZ covers FunctionW", "ClassA extends ClassB"
- **Metadata:** Name, type, file path, line range per node
- **Privacy:** Structural metadata only — NO source code content in the graph

### Supported Languages (19)
Python, TypeScript, JavaScript, Go, Rust, Java, C#, Ruby, Kotlin, Swift, PHP, C/C++, Vue SFC, Solidity, Dart, R, Perl, Lua, Jupyter/Databricks notebooks.

---

## Installation

### Prerequisites
- Python 3.9+ (`python3 --version`)
- pip or pipx installed
- An MCP-compatible AI client (AG Kit, Claude Code, Cursor, Windsurf, Zed)
- Git-tracked codebase (for incremental updates)

### Step 1: Install the Package

```bash
# Recommended: isolated environment
pipx install code-review-graph

# Alternative: fastest, no permanent install
uvx code-review-graph install

# Alternative: global pip
pip install code-review-graph
```

### Step 2: Configure MCP Client

```bash
# Auto-detect all supported tools
code-review-graph install

# Or target a specific platform
code-review-graph install --platform claude-code
code-review-graph install --platform cursor
code-review-graph install --platform windsurf
```

> **Restart your editor** after this step. The MCP server activates on restart.

### Step 3: Build the Initial Graph

```bash
cd /your/project
code-review-graph build
```

| Codebase Size | Expected Build Time |
|---------------|---------------------|
| 500 files | 10–30 seconds |
| 5,000 files | 2–5 minutes |
| 27,000 files | 5–10 minutes |

### Step 4: Enable Watch Mode (Recommended)

From Manas8114/agentic-os, MIT.

More from Manas8114/agentic-os