code-review-graph Hands-On SOP: Build an AI Knowledge Graph for Your Codebase in 4 Steps

I have a recurring problem with AI coding tools: when I ask one to review a change, it reads through half the repository, burning tokens like crazy while the actually relevant context gets buried in noise. It took me a while to realize the model isn't dumb. It just doesn't have a map, so it searches blindly.

code-review-graph is that map. It uses Tree-sitter to parse your codebase into a knowledge graph stored in SQLite. When the AI reviews code, it queries the graph first, calculates the affected scope, and only reads the files that matter. Across 6 repositories, token usage dropped 38 to 528x. In a monorepo with 27,700+ files, only about 15 actually get read.

This is the hands-on SOP I put together after installing it myself. Four steps: install, build, use, review. Each comes with real commands and copyable prompts, plus a pitfall section at the end. If you want the design rationale first, check the companion open-source intro piece in this batch. This one is purely about getting it running.

1. What Problem Does It Solve

AI coding tools (Cursor, Claude Code, Codex, etc.) review code by defaulting to stuffing relevant files into context. Fine for small projects, but scale up and it breaks: out of tens of thousands of files, most have nothing to do with your change, yet the model reads them all to figure out the impact. Tokens wasted, attention diluted, review quality drops.

code-review-graph takes a direct approach: pre-compute the structural relationships in your codebase and store them as a SQLite graph. Nodes are functions, classes, imports. Edges are calls, inheritance, test coverage. When reviewing, the AI queries the graph first, calculates the blast radius (affected callers, dependencies, tests), then reads only those files. No full scan.

2. Install: Set Up the Platform

Prerequisite: Python 3.10+. I recommend installing uv, which gives you uvx later. If you don't have uv, pip or pipx work fine too.

First, install code-review-graph itself:

# Option 1: pip
pip install code-review-graph

# Option 2: pipx (recommended, isolated environment)
pipx install code-review-graph

Installing the package isn't enough. The key step is connecting it to your AI coding tool:

# Auto-detect and configure all supported AI coding tools
code-review-graph install

# If you only use one platform, specify it to avoid extra config
code-review-graph install --platform cursor
# Other options: claude-code / codex / gemini-cli / copilot / kiro, etc.

This command does three things behind the scenes: writes the correct MCP config, installs the platform's native hooks/skills, and injects graph instructions into the platform's rules. In plain terms, it tells your AI tool to check the graph before reviewing code.

You must restart your editor or tool after installation. MCP configs don't hot-reload. Skip the restart and it's like you never installed it. More on this pitfall later.

3. Build: Construct the Code Graph

With the platform configured, the next step is parsing your codebase into a graph:

code-review-graph build

This command uses Tree-sitter to parse your code into an AST, extracting functions, classes, and imports as nodes, and calls, inheritance, and test coverage as edges, then storing everything in a SQLite graph database. A 500-file project takes about 10 seconds.

The principle in one sentence: Tree-sitter parses code into an abstract syntax tree. Nodes are functions/classes/imports, edges are call/inheritance/test-coverage relationships, all stored in a SQLite graph database. During review, the graph tool calculates the minimal necessary file set from these relationships, and the AI reads only those files. It's essentially trading space for time. Build the graph once, and every subsequent review benefits.

4. Use: Trigger the Graph and Incremental Updates

With the graph built, go back to your AI coding tool and tell it:

Build the code review graph for this project

After that, watch mode and supported platform hooks automatically update the graph incrementally. File saves trigger updates, commit hooks trigger updates. Incremental speed is fast: a 2,900-file project re-indexes in under 2 seconds. You don't need to manually rebuild after every change.

The point here is that the graph isn't a one-time snapshot. It follows your code as it evolves. You write, save, and commit normally, and the graph updates silently in the background. Next time you ask for a review, the AI always has the latest structure.

5. Review: Audit Code with the Graph

This is where it pays off. When you ask the AI to review changes, it first queries the graph via MCP, calculates the blast radius of the change (affected callers, dependencies, tests), then reads only those files.

Try this prompt:

Review the changes in src/auth/, what's the blast radius?

The AI queries the graph to locate changes under src/auth/, calculates which callers, dependencies, and tests are affected, then pulls only those files into context for review. The results are concrete: across 6 repositories, token usage dropped 38 to 528x, and the average number of files read per question dropped 93x. In a monorepo with 27,700+ files, only about 15 get read.

The contrast makes the gap obvious: without the graph, the AI might read dozens or hundreds of files to understand the impact of a single change. With the graph, it knows exactly which files are affected, leaving the context window for the code that actually matters.

6. Uninstall and Cleanup

If you want to remove it, uninstall is symmetric. It only deletes code-review-graph's own files and won't touch your other MCP configs, hooks, or skills.

# Preview what will be deleted, without actually executing
code-review-graph uninstall --dry-run

# Execute after confirming
code-review-graph uninstall --yes

# Clean up all registered repositories
code-review-graph uninstall --all-repos

# Only remove platform integration, keep the graph database (reusable next time)
code-review-graph uninstall --keep-data

My habit is to always run --dry-run first to see what gets deleted before committing. The --keep-data option is quite practical: if you just want to temporarily disable the integration but keep the built graph, you won't need to rebuild when you reinstall later.

7. Pitfalls

A few things tripped me up during installation.

Pitfall 1: Forgetting to restart the editor. The install command writes the MCP config, but editors don't auto-reload it. You go back to your tool, find the graph unresponsive, assume the installation failed, and waste time debugging. It's just missing a restart. First thing after install: close the editor, reopen it.

Pitfall 2: Tree-sitter doesn't support your language. Tree-sitter parser coverage is limited. If your language isn't on the supported list, you need to manually create .code-review-graph/languages.toml in the project root, mapping file extensions to the corresponding grammar in tree_sitter_language_pack, and specifying node types (function/class/import/call). First-timers often miss node types, resulting in a graph with missing edges and nodes, which makes the blast radius calculation inaccurate.

Pitfall 3: Mixing uvx and pip. The two installation methods generate slightly different configs. The install command auto-detects whether you installed via uvx or pip and generates the corresponding config, but if you switch methods midway, old configs may linger. Pick one method and stick with it.

Pitfall 4: Slow initial build on large monorepos. Very large repos take a while on the first build. Run build to completion first, then enable watch mode. Don't expect to build and use simultaneously on the first run. Until build finishes, the graph is incomplete and review results will be degraded.

Pitfall 5: Skipping --dry-run before uninstall. Even though uninstall only removes CRG's own files, running --yes directly without previewing, especially if you've registered multiple repos, might delete more than expected. Make previewing a habit, even just a quick scan.

8. Wrap-Up

The whole flow is four steps: install config, build graph, trigger incremental updates, review with the graph. Once configured, your AI coding tool's token consumption during code review drops significantly, and review quality improves because attention is focused. The biggest gain isn't even token savings. It's that the AI gains a structural understanding of your codebase, pinpointing impact scope instead of guessing through a sea of files.

This is the hands-on piece, paired with the companion article in this batch: "code-review-graph: A Local Code Knowledge Graph to Lighten the Load on AI Coding Tools." That one covers what and why. This one covers how. Read them together to go from understanding to deployment in one straight line.

References

• code-review-graph GitHub repository: https://github.com/tirth8205/code-review-graph
• PyPI package page: https://pypi.org/project/code-review-graph/
• Project website: https://code-review-graph.com