AI coding tools often re-read large parts of a codebase to review a change. code-review-graph builds a structural map of the code with Tree-sitter, keeps it updated incrementally, and serves compact context over MCP, so the assistant reads only the files a change touches.
What it does
- Maps your code. Functions, classes, imports, calls and tests become one graph.
- Shows what a change can break. The callers, dependents and tests it can reach, with a risk score.
- Stays up to date. Hooks and watch mode parse again only the files that changed.
- Works with your AI tools. One
install sets up each tool it finds.
- Stays on your machine. One SQLite file, no cloud service; cloud embeddings are opt-in.
Quick Start
Requires Python 3.10+.
uv tool install code-review-graph # or: pipx install / pip install code-review-graph
code-review-graph install # set up the AI coding tools found on this machine
code-review-graph build # parse the codebase
code-review-graph detect-changes --brief # see what your last change touches
Restart the editor or tool, then open the project and ask the assistant:
Review my changes
Undo everything with code-review-graph uninstall (preview with --dry-run). If something does not work, run code-review-graph doctor: it checks the setup and changes nothing.
install looks for AI coding tools on this machine and sets up only the ones it finds. For each it writes an MCP server entry, installs hooks and skills where the tool supports them, and adds graph instructions to its rules file. It then names the tools it did not find; add one anyway with install --platform NAME.
Nothing is written until install has listed the files it will change and you have answered its question about instruction files. With no terminal, as when an AI agent runs it, it takes the default answer, yes, and says so; --no-instructions skips those files. install --dry-run shows each change as a diff and writes nothing. Restart the editor or tool afterwards.
The MCP entry and every hook run the copy of code-review-graph that ran install. The MCP entry uses poetry run or uv run inside a Poetry or uv project, uvx when install itself ran from uvx or uv tool install, and otherwise the Python that ran install. Hooks name that Python (or uvx), and run the code-review-graph on PATH if it is gone. After an upgrade, run install again.
The files install writes, such as .claude/ and .mcp.json, stay visible to git in case your team commits them. Until git tracks them, build and reviews leave them out, so your first review shows your own change; install lists them in .code-review-graph/install-manifest.json. install --gitignore adds the ones that run created to a marked block in .gitignore; uninstall removes the block.
For Codex, the installer also places a global code-review-graph Skill under
$CODEX_HOME/skills/code-review-graph/ (default:
~/.codex/skills/code-review-graph/). It prefers CRG MCP tools and falls back
to the bundled read-only CLI when MCP is unavailable; a missing, empty, or
stale graph never triggers an implicit build or update. WSL and Windows Codex
runtimes have separate CODEX_HOME directories and tool inventories, so
install and refresh the runtime that will execute the task.
To configure one platform, pass --platform with one of codex, claude-code, cursor, windsurf, zed, continue, opencode, mimo, antigravity, gemini-cli, qwen, kiro, qoder, copilot, copilot-cli, codebuddy, hermes, or dsh:
code-review-graph install --platform cursor
code-review-graph install --platform codebuddy
A platform named this way is set up even when install does not find it. Config file locations are listed in docs/USAGE.md.
uninstall removes CRG-owned files and entries from a Git or SVN working tree and leaves other MCP servers, hooks, skills and JSONC comments alone. Run it from anywhere inside the tree. Shared config files are replaced atomically, so a failed write leaves the original intact. A config file install made, which git does not track and which holds nothing else, is removed along with the empty folders install made. With no terminal it takes the default answer, no, and says to pass --yes.
code-review-graph uninstall --dry-run # preview only
code-review-graph uninstall # preview, confirm, apply
code-review-graph uninstall --yes # apply without prompting
code-review-graph uninstall --all-repos # also clean every registered repository
code-review-graph uninstall --keep-data # remove integrations, keep graph databases
code-review-graph uninstall --keep-user-configs --repo . # this project only
Build time scales with repository size; a cold build of a ~3,000-file repository took about 40 seconds (measured). After that, hooks and watch mode keep the graph updated. If some files fail to parse, the result has status partial and names them in its summary; the CLI also prints a Warning: line on stderr, and those files keep their previous graph rows. A build that finds no source files warns on stderr and asks whether you are in the project root.
pip install -U code-review-graph # or: pipx upgrade / uv tool upgrade code-review-graph
code-review-graph doctor # every copy, MCP entry and hook, and the version each runs
code-review-graph install --dry-run # see what changes, then run install
code-review-graph build # once: new file types and fixes reach only re-parsed files
This is the beginning of the README. Read the rest at the original. Read the full README ↗
