code-review-graph Tutorial: PR Impact Analysis and Incremental CI Graphs for Codex and Claude Code

code-review-graph is a local-first code-structure graph tool. It uses Tree-sitter to parse source code, writes calls, imports, inheritance, tests, and other relationships to a SQLite graph database inside the repository, and exposes structured context to Codex, Claude Code, and other tools through its CLI and MCP server.

Rather than “let AI automatically approve PR”, it solves the problem of reducing the cost of AI re-searching the entire repository for every review and helping reviewers locate cross-file calls, potential impact areas, and testing gaps. The final conclusion still comes back to Git diff, test results and human judgment.

Project address: tirth8205/code-review-graph

When is it worth using?

More suitable for:

Repositories containing hundreds to thousands of files;
monorepo or multilingual project;
Frequently review cross-file and cross-module modifications;
Need to track callers, dependencies, tests and execution flows;
Want core graph data to stay local.

Not necessarily suitable for:

Small projects with only a few files;
Modifications are concentrated in a single independent file;
Mainly review documents, configurations or pictures;
The team is not prepared to maintain index freshness;
One-time task, faster to read diff directly.

For a small diff, the graph query result may be larger than the original diff. Minimal context and change detection should be used first before deciding whether to expand the impact radius.

Working principle and data boundaries

The main process is:

1
2
3
4
5
6


Git 跟踪文件
  -> Tree-sitter 解析
  -> 节点与关系
  -> .code-review-graph/ SQLite
  -> CLI / MCP 查询
  -> Codex、Claude Code 或人工审查

Core composition and querying can be done locally, without requiring code to be uploaded to the cloud. Optional embeddings may use on-premises models or cloud providers; code shipping boundaries and team policies should be confirmed before enabling cloud embeddings.

In the Git repository, only tracked files returned by git ls-files are indexed by default. To exclude generated files or third-party code that are still tracked by Git, create in the repository root:

1
2
3
4
5


# .code-review-graphignore
generated/**
*.generated.ts
vendor/**
node_modules/**

Graph databases are typically located at:

1

.code-review-graph/

It is a rebuildable artifact and should not be submitted unconditionally to Git.

Prepare Python environment before installation

Project requirements Python 3.10 or higher:

1
2


python --version
git --version

It is recommended to use pipx to isolate the global CLI:

1
2
3


python -m pip install --user pipx
python -m pipx ensurepath
pipx install code-review-graph

You can also install it directly:

1

python -m pip install code-review-graph

Post-installation verification:

1
2


code-review-graph --help
code-review-graph status

If the shell cannot find the command, first check whether the bin directory of Python Scripts or pipx has entered PATH. Do not repeatedly install multiple copies.

Configure MCP for Codex or Claude Code

The unified installation command will detect the installed platform:

1

code-review-graph install

Configure only Codex:

1

code-review-graph install --platform codex

Configure only Claude Code:

1

code-review-graph install --platform claude-code

The installer will write the corresponding MCP configuration and add hooks, skills or rule descriptions on supported platforms. Back up the existing configuration before execution and check the diff after execution to avoid accidentally overwriting team customizations.

Restart the AI tool when finished. Claude Code can check connectivity via /mcp; other clients should confirm that the code-review-graph server is connected and lists the tools.

Build the code graph for the first time

Enter the root directory of the repository to analyze:

1
2
3
4


git rev-parse --show-toplevel
git status --short
code-review-graph build
code-review-graph status

status should at least show non-zero file, node, and edge counts, and record build branches and commits. If the node is zero, common reasons include:

The current directory is not the target repository;
The file is not tracked by Git;
The extension is not recognized by the parser;
.code-review-graphignore excludes all content;
The build failed midway.

Before formal use, select a known function to test the structure query to confirm that the calling relationship can return to the real file.

Daily updates and change detection

Run incremental updates after code changes:

1
2


code-review-graph update
code-review-graph status

When concise output and context-saving information are needed:

1
2


code-review-graph update --brief
code-review-graph detect-changes --brief

update Update change files; detect-changes analyze current Git changes and impact. The two have different meanings, and you should not assume that the graph is up to date just because detect-changes works.

For long-term development, you can use:

1

code-review-graph watch

However, in large repositories CPU, file listening caps, and generated directory noise should be observed; CI environments are generally better suited to explicit execution of build or update.

Let Codex or Claude Code review PR

After installing MCP and completing the composition, you can propose:

1
2
3


使用 code-review-graph 审查当前分支相对 main 的变化。
先检测变更，再给出跨文件影响、调用者、相关测试和测试缺口。
只读取必要上下文；所有结论附上文件路径，并与 git diff 对照。

Projects also provide workflow templates, such as:

review_changes: Review current changes;
architecture_map: Understand the architecture;
debug_issue: troubleshoot along relationships;
onboard_developer: Generate getting started context;
pre_merge_check: Pre-merge check.

Whether using templates or free prompts, the order should be maintained:

Confirm that the graph database is fresh;
Read the actual Git diff;
Query changed nodes;
Expand callers, dependencies and tests;
Run real tests;
Manual review conclusion.

How to interpret Token savings

Currently CLI can display context saving panels in detect-changes --brief and update --brief. The default number is a project-defined estimate and does not equal the exact Token in the bill.

To use tokenizer cross-validation, you need to install additional dependencies and add --verify:

1
2


python -m pip install tiktoken
code-review-graph detect-changes --brief --verify

Record during assessment:

Raw diff and repository size;
The context length returned by the graph;
The file that the AI actually continues to read;
False negatives and false positives;
Review takes time;
Test whether any problems not shown in the picture are found.

Don’t apply the highest multiple from the official benchmark directly to the team budget. Small repositories, single file modifications, language parsing coverage, and questioning methods all change the results.

What the GitHub Actions example does

The following is a self-maintenance example compiled by this site, not the GitHub Action officially released by the project. It only installs CLI, restores the local map cache, performs incremental updates, and outputs reports. It does not automatically approve PR or write the results back to the comment area.

First create:

1

.github/workflows/code-review-graph.yml

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54


name: code-review-graph

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read

jobs:
  impact:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install
        run: python -m pip install code-review-graph

      - name: Restore graph cache
        id: graph-cache
        uses: actions/cache@v4
        with:
          path: .code-review-graph
          key: crg-${{ runner.os }}-${{ github.event.pull_request.base.sha }}
          restore-keys: |
            crg-${{ runner.os }}-

      - name: Build or update graph
        shell: bash
        run: |
          if [ -d .code-review-graph ]; then
            code-review-graph update --brief
          else
            code-review-graph build
          fi
          code-review-graph status

      - name: Analyze changes
        run: code-review-graph detect-changes --brief | tee crg-review.txt

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: code-review-graph-report
          path: crg-review.txt
          if-no-files-found: warn

When enabling it for the first time, it is recommended to remove the cache step, confirm that the clean build is successful, and then add the cache. Caching is not a source of correctness; a complete rebuild should be allowed after changes to the parser, schema, or project structure.

Cache key and graph freshness

The example submits the PR baseline into the cache key in order to reduce the probability of directly reusing old images between different baselines. You can also add a summary of the dependency lock file:

1

key: crg-${{ runner.os }}-${{ hashFiles('pyproject.toml', 'package-lock.json') }}-${{ github.event.pull_request.base.sha }}

The cache should be deleted and restarted in the following cases build:

Upgrade code-review-graph or Tree-sitter parser;
Modify exclusion rules;
Massive directory renaming;
Abnormal decline in graph statistics;
Local and CI results cannot be reproduced;
Schema or database compatibility changes.

The acceptance cache hit should not only check the Actions display cache-hit, but also check the branches, commits, number of files, number of nodes, and number of edges of status.

Permission boundaries for Fork PR

Core analysis only needs read access to the checked-out source code. It does not require repository write permission and should not use deployment secrets. Keep the following permissions:

1
2


permissions:
  contents: read

Do not use pull_request_target on unreviewed Fork code to execute commands after checking out the PR head; this combination may expose underlying repository permissions or Secret.

If comments are to be automatically posted in the future, they should be broken into independent controlled steps and the report content, permissions and sources should be reviewed. The most secure first version only uploads artifacts for review by maintainers.

Monorepo and Big Changes

.code-review-graphignore can be used in a monorepo to exclude build directories and vendors that are explicitly not subject to review. Don’t exclude shared libraries for speed, otherwise the analysis will lose cross-package relationships.

Very large diffs should first obtain a list of files:

1

git diff --name-only origin/main...HEAD

If the automatic detection of MCP does not respond for a long time, you can pass a clear list of changed files to the impact analysis tool to avoid repeated execution of Git detection with an excessive scope on the backend.

The project also provides boundary environment variables for limiting very large fronts, such as CRG_MAX_CHANGED_FUNCS, CRG_MAX_TRANSITIVE_FRONTIER, and CRG_TOOL_TIMEOUT. Record the default behavior before adjusting. Limits that are too low will reduce recalls.

Troubleshoot Windows MCP connection failures and stalls

CLI is normal but MCP reports Invalid JSON: EOF while parsing or Connection closed:

Upgrade code-review-graph;
Execute install again to update the configuration;
Confirm that version FastMCP meets the current requirements of the project;
Let MCP directly execute .exe in the virtual environment;
Set PYTHONUTF8=1;
Restart the client and view the MCP log.

Schematic configuration:

1
2
3
4
5
6
7


{
  "code-review-graph": {
    "command": "C:\\path\\to\\venv\\Scripts\\code-review-graph.exe",
    "args": ["serve", "--repo", "C:\\path\\to\\project"],
    "env": {"PYTHONUTF8": "1"}
  }
}

CLI’s status and detect-changes are very fast, but when the MCP call times out, the result of git diff --name-only is first explicitly passed to the tool to distinguish between the slow change detection of Git and the slow graph query.

How to recover when graph data is wrong

Record the scene first:

1
2
3


code-review-graph status
git rev-parse HEAD
git status --short

Then perform an incremental update:

1
2


code-review-graph update
code-review-graph status

If the result is still incorrect, back up or remove the rebuildable .code-review-graph directory and perform a full build. Before removal, confirm that the directory is inside the intended repository so that unrelated data is not deleted.

This should also be re-run after upgrading:

1
2
3


python -m pip install -U code-review-graph
code-review-graph install
code-review-graph build

install is used to refresh the platform configuration, and build is used to refresh the graph data. Do not confuse the two steps.

Uninstall and rollback

Preview first:

1

code-review-graph uninstall --dry-run

Uninstall after confirmation:

1

code-review-graph uninstall

Only remove the integration and keep the graph data:

1

code-review-graph uninstall --keep-data

Then check whether there are any remaining MCP items in the Codex, Claude Code and other configurations, and confirm that the original configuration backup can be restored.

Final acceptance checklist

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


[ ] Python 版本至少为 3.10
[ ] CLI --help 和 status 可运行
[ ] build 后文件、节点和边数量非零
[ ] .code-review-graph 已加入忽略策略
[ ] Codex 或 Claude Code 能列出 MCP 工具
[ ] update 后图对应当前分支与提交
[ ] detect-changes 结果能回到真实 Git diff
[ ] 影响范围和测试缺口经过人工核对
[ ] Token 节省区分估算与 --verify 结果
[ ] CI 仅有 contents: read 权限
[ ] Fork PR 不接触 Secret
[ ] 缓存失效时可以完整重建
[ ] 卸载和恢复步骤已验证

Summary

code-review-graph works as a structural index for AI-assisted code review, not as an automated approver. A reliable workflow is to build the graph in the correct repository, keep it incrementally updated, retrieve only the necessary context through MCP, and confirm conclusions with the Git diff, tests, and human review.

When accessing GitHub Actions, you should first ensure that the clean build is reproducible, and then gradually add cache and artifacts. Permissions remain read-only, Fork PR does not use Secret, and being able to fall back to a normal diff and full rebuild when the graph fails is more important than chasing the highest Token savings in a single benchmark.