Skip to content
Back to search

code-review-graph

Local-first code intelligence graph for MCP and CLI. Builds a persistent map of your codebase so AI coding tools read only what matters, with benchmarked context reductions on reviews and large-repo workflows.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tirth8205/code-review-graph with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tirth8205/code-review-graph'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tirth8205-code-review-graph/badge.svg)](/listings/tirth8205-code-review-graph)

HTML

<a href="/listings/tirth8205-code-review-graph"><img src="/api/listings/tirth8205-code-review-graph/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install code-review-graph          # or: pipx install code-review-graph
code-review-graph install              # detect installed AI coding tools and configure each one
code-review-graph build                # parse the codebase

`install` detects which AI coding tools you have, writes an MCP server entry for each, installs hooks and skills where the platform supports them, and adds graph instructions to the platform's rules file. The MCP entry uses `poetry run` or `uv run` inside a Poetry or uv project environment, `uvx code-review-graph serve` when `uvx` is on PATH, and otherwise the current Python interpreter. Restart the editor or tool afterwards.

<p align="center"> </p>

To configure one platform, pass `--platform` with one of `codex`, `claude-code`, `cursor`, `windsurf`, `zed`, `continue`, `opencode`, `antigravity`, `gemini-cli`, `qwen`, `kiro`, `qoder`, `copilot`, `copilot-cli`, `codebuddy`, or `hermes`:

code-review-graph install --platform cursor
code-review-graph install --platform codebuddy

Config file locations are listed in [docs/USAGE.md](docs/USAGE.md#supported-platforms). Requires Python 3.10+.

`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.

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

Then open the project and ask the assistant:

Build the code review graph for this project

Build time scales with repository size; a cold build of a ~3,000-file repository took about 40 seconds ([measured](docs/REPRODUCING.md#incremental-update-latency)). 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 932 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <h1 align="center">code-review-graph</h1>
  2. <p align="center">
  3. <a href="https://trendshift.io/repositories/23329?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-23329"
  4. target="_blank"
  5. rel="noopener noreferrer">
  6. <img src="https://trendshift.io/api/badge/repositories/23329"
  7. alt="tirth8205%2Fcode-review-graph | Trendshift"
  8. width="250"
  9. height="55" />
  10. </a>
  11. </p>
  12. <p align="center">
  13. <strong>A local code knowledge graph that gives AI coding tools precise review context over MCP.</strong>
  14. </p>
  15. <p align="center">
  16. <a href="README.md">English</a> |
  17. <a href="README.zh-CN.md">简体中文</a> |
  18. <a href="README.ja-JP.md">日本語</a> |
  19. <a href="README.ko-KR.md">한국어</a> |
  20. <a href="README.hi-IN.md">हिन्दी</a>
  21. </p>
  22. <p align="center">
  23. <a href="https://pypi.org/project/code-review-graph/"><img src="https://img.shields.io/pypi/v/code-review-graph?style=flat-square&color=blue" alt="PyPI"></a>
  24. <a href="https://pepy.tech/project/code-review-graph"><img src="https://img.shields.io/pepy/dt/code-review-graph?style=flat-square" alt="Downloads"></a>
  25. <a href="https://github.com/tirth8205/code-review-graph/stargazers"><img src="https://img.shields.io/github/stars/tirth8205/code-review-graph?style=flat-square" alt="Stars"></a>
  26. <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="MIT Licence"></a>
  27. <a href="https://github.com/tirth8205/code-review-graph/actions/workflows/ci.yml"><img src="https://github.com/tirth8205/code-review-graph/actions/workflows/ci.yml/badge.svg?branch=staging" alt="CI"></a>
  28. <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg?style=flat-square" alt="Python 3.10+"></a>
  29. <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green.svg?style=flat-square" alt="MCP"></a>
  30. <a href="https://code-review-graph.com"><img src="https://img.shields.io/badge/website-code--review--graph.com-blue?style=flat-square" alt="Website"></a>
  31. <a href="https://discord.gg/3p58KXqGFN"><img src="https://img.shields.io/badge/discord-join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
  32. </p>
  33. <p align="center">
  34. <a href="docs/USAGE.md">Usage</a> ·
  35. <a href="docs/COMMANDS.md">Commands</a> ·
  36. <a href="docs/FAQ.md">FAQ</a> ·
  37. <a href="docs/TROUBLESHOOTING.md">Troubleshooting</a> ·
  38. <a href="docs/FEATURES.md">What's new</a> ·
  39. <a href="CHANGELOG.md">Changelog</a> ·
  40. <a href="docs/GITHUB_ACTION.md">GitHub Action</a> ·
  41. <a href="docs/REPRODUCING.md">Reproducing the benchmarks</a> ·
  42. <a href="docs/ROADMAP.md">Roadmap</a> ·
  43. <a href="docs/INDEX.md">All docs</a>
  44. </p>
  45. <br>
  46. 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](https://tree-sitter.github.io/tree-sitter/), keeps it updated incrementally, and serves compact context over [MCP](https://modelcontextprotocol.io/), so the assistant reads only the files a change touches.
  47. <p align="center">
  48. <img src="diagrams/diagram1_before_vs_after.png" alt="The Token Problem: reading flask's whole corpus costs 143,594 tokens, a graph answer costs 2,196 (65x fewer)" width="85%" />
  49. </p>
  50. **What it does**
  51. - **Maps your code.** Functions, classes, imports, calls and tests become one graph.
  52. - **Shows what a change can break.** The callers, dependents and tests it can reach, with a risk score.
  53. - **Stays up to date.** Hooks and watch mode parse again only the files that changed.
  54. - **Works with your AI tools.** One `install` sets up each tool it finds.
  55. - **Stays on your machine.** One SQLite file, no cloud service; cloud embeddings are opt-in.
  56. ---
  57. ## Quick Start
  58. Requires Python 3.10+.
  59. ```bash
  60. uv tool install code-review-graph # or: pipx install / pip install code-review-graph
  61. code-review-graph install # set up the AI coding tools found on this machine
  62. code-review-graph build # parse the codebase
  63. code-review-graph detect-changes --brief # see what your last change touches
  64. ```
  65. Restart the editor or tool, then open the project and ask the assistant:
  66. ```
  67. Review my changes
  68. ```
  69. 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.
  70. <details>
  71. <summary><strong>What <code>install</code> changes, and how to preview it first</strong></summary>
  72. <br>
  73. `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`.
  74. 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.
  75. 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.
  76. 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.
  77. For Codex, the installer also places a global `code-review-graph` Skill under
  78. `$CODEX_HOME/skills/code-review-graph/` (default:
  79. `~/.codex/skills/code-review-graph/`). It prefers CRG MCP tools and falls back
  80. to the bundled read-only CLI when MCP is unavailable; a missing, empty, or
  81. stale graph never triggers an implicit build or update. WSL and Windows Codex
  82. runtimes have separate `CODEX_HOME` directories and tool inventories, so
  83. install and refresh the runtime that will execute the task.
  84. </details>
  85. <details>
  86. <summary><strong>Every supported platform, and how to set up just one</strong></summary>
  87. <br>
  88. <p align="center">
  89. <img src="diagrams/diagram8_supported_platforms.png" alt="One install, every platform: detects Codex, Claude Code, CodeBuddy Code, Cursor, Windsurf, Zed, Continue, OpenCode, MiMo Code, Antigravity, Gemini CLI, Qwen Code, Qoder, Kiro, GitHub Copilot, GitHub Copilot CLI, Hermes Agent and DeepSeek Harness" width="85%" />
  90. </p>
  91. 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`:
  92. ```bash
  93. code-review-graph install --platform cursor
  94. code-review-graph install --platform codebuddy
  95. ```
  96. A platform named this way is set up even when `install` does not find it. Config file locations are listed in [docs/USAGE.md](docs/USAGE.md#supported-platforms).
  97. </details>
  98. <details>
  99. <summary><strong>More ways to <code>uninstall</code></strong></summary>
  100. <br>
  101. `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`.
  102. ```bash
  103. code-review-graph uninstall --dry-run # preview only
  104. code-review-graph uninstall # preview, confirm, apply
  105. code-review-graph uninstall --yes # apply without prompting
  106. code-review-graph uninstall --all-repos # also clean every registered repository
  107. code-review-graph uninstall --keep-data # remove integrations, keep graph databases
  108. code-review-graph uninstall --keep-user-configs --repo . # this project only
  109. ```
  110. </details>
  111. <details>
  112. <summary><strong>How long a build takes, and what a partial build means</strong></summary>
  113. <br>
  114. Build time scales with repository size; a cold build of a ~3,000-file repository took about 40 seconds ([measured](docs/REPRODUCING.md#incremental-update-latency)). 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.
  115. </details>
  116. <details>
  117. <summary><strong>Upgrading from 2.3.x</strong></summary>
  118. <br>
  119. ```bash
  120. pip install -U code-review-graph # or: pipx upgrade / uv tool upgrade code-review-graph
  121. code-review-graph doctor # every copy, MCP entry and hook, and the version each runs
  122. code-review-graph install --dry-run # see what changes, then run install
  123. code-review-graph build # once: new file types and fixes reach only re-parsed files
  124. ```
  125. Upgrade every copy you have. The MCP entry, the git and editor hooks and `crg-daemon` can each run a different one, and once 2.4.0 or later has opened the graph, a 2.3.9 copy refuses it and an older 2.3.x copy can break it. Run `install` again so the entry and the hooks run the new copy, then restart the editor (and run `crg-daemon restart` if you use the daemon).
  126. The first command of 2.4.0 or later moves the graph to schema 15. If you use the VS Code extension, it needs version 0.4.0 to read that graph. Full list: [upgrade notes](CHANGELOG.md#upgrade-notes).
  127. </details>
  128. ## How It Works
  129. The repository is parsed into ASTs with Tree-sitter and stored as a graph of nodes (functions, classes, imports) and edges (calls, inheritance, test coverage). At review time the graph is queried for the smallest set of files the assistant needs to read.
  130. <details>
  131. <summary><strong>Two diagrams: how the assistant uses the graph, and the build pipeline</strong></summary>
  132. <br>
  133. <p align="center">
  134. <img src="diagrams/diagram7_mcp_integration_flow.png" alt="How the assistant uses the graph: the user asks for a review, the assistant calls MCP tools, the graph returns blast radius and risk scores, the assistant reads only the affected files" width="80%" />
  135. </p>
  136. <p align="center">
  137. <img src="diagrams/diagram2_architecture_pipeline.png" alt="Architecture pipeline: Repository to Tree-sitter parser to SQLite graph to blast radius to minimal review set" width="100%" />
  138. </p>
  139. </details>
  140. ### Blast-radius analysis
  141. <details>
  142. <summary><strong>Every caller, dependent and test a change can affect</strong></summary>
  143. <br>
  144. When a file changes, the graph traces every caller, dependent and test that could be affected. The assistant reads those files instead of scanning the whole project.
  145. <p align="center">
  146. <img src="diagrams/diagram3_blast_radius.png" alt="Blast radius: a change to login() propagates to callers, dependents, and tests" width="70%" />
  147. </p>
  148. </details>
  149. ### Incremental updates
  150. <details>
  151. <summary><strong>Only changed files are parsed again (about 2.5 s for a two-file edit)</strong></summary>
  152. <br>
  153. Editor hooks, git hooks (pre-commit, post-checkout, post-merge, post-rewrite) and watch mode trigger incremental updates. The hooks update quietly; on each commit the pre-commit hook prints only the short review from `detect-changes --brief`. The update diffs changed files, finds their dependents through the graph's import and call edges, and re-parses only the files whose SHA-256 hash changed. On a ~3,000-file project (django) a two-file edit re-indexes in about 2.5 seconds on the path the hooks use, of which ~1.4 s is process start-up; a no-op update costs only that start-up. See [Incremental update latency](docs/REPRODUCING.md#incremental-update-latency).
  154. <p align="center">
  155. <img src="diagrams/diagram4_incremental_update.png" alt="Incremental update flow: a hook or watch update triggers a git diff, dependents are found through graph edges, and only files whose SHA-256 hash changed are re-parsed" width="90%" />
  156. </p>
  157. </details>
  158. ### Whole codebase or targeted answer?
  159. <details>
  160. <summary><strong>A slice of the graph shaped to the question, not the whole codebase</strong></summary>
  161. <br>
  162. Instead of feeding a whole corpus to the model, the graph returns a slice shaped to the question. In the 2026-08-02 capture of this repository at `84bde354`, 208,821 source tokens became ~3,190 tokens per question. The repository has grown a lot since that snapshot, so both numbers are larger today.
  163. <p align="center">
  164. <img src="diagrams/diagram6_monorepo_funnel.png" alt="code-review-graph at the 84bde354 snapshot: 208,821 source tokens funnel down to ~3,190 token graph responses, about 65x fewer tokens per question" width="80%" />
  165. </p>
  166. </details>
  167. ### Language coverage and notebooks
  168. <details>
  169. <summary><strong>Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, C# and many more, plus notebooks: the full list</strong></summary>
  170. <br>
  171. <p align="center">
  172. <img src="diagrams/diagram9_language_coverage.png" alt="Language coverage by category: Web, Backend, Systems, Mobile, Scripting, Shells, Domain, Config and Other, plus Jupyter and Databricks notebooks" width="90%" />
  173. </p>
  174. The parser extracts functions, classes, imports, call sites, inheritance and tests, using Tree-sitter where a grammar exists and targeted fallbacks elsewhere. Supported: Python, JavaScript/TypeScript/TSX (including `.mjs`, `.cjs`, `.mts` and `.cts`), Go, Rust, Java, C/C++, C#, VB.NET, Ruby, Kotlin (`.kt`, `.kts`), Swift, PHP, Scala, Solidity, Dart, R, Perl, Lua/Luau, Objective-C, shell scripts, Elixir, Zig, PowerShell, Julia, ReScript, GDScript, Nix, Verilog/SystemVerilog, SQL/PL/SQL (Oracle) and dbt models, Terraform/OpenTofu (`.tf`, and Terraform blocks in `.hcl` files; an `.hcl` file with no Terraform blocks keeps only a file node), Ansible YAML (playbooks, roles, tasks), Spring Boot application config (`application.properties`, `application.yml`, `application.yaml` and their `application-<profile>` variants; key names and value types only, never values), value-free generic YAML structure (translation files in folders such as `locales/` become file nodes only), XSLT stylesheets (`.xsl`, `.xslt`), value-free JSON structure (`.json`; translation, test, docs, example and data files keep only a file node, and lock files are skipped), Vue/Svelte SFCs, HTML pages (`.html`, `.htm`; inline scripts, plus `div`, `section` and `article` blocks with an id as `DocSection` nodes), Astro files (parsed with the TypeScript grammar), Jupyter and Databricks notebooks (`.ipynb`, plus Databricks `.py` exports), Perl XS files (`.xs`), Robot Framework files (`.robot`, `.resource`), and Liquid templates (`.liquid`). Other `.properties` files are not treated as source code.
  175. PHP projects also get repository-bounded Composer PSR-4 resolution, Blade template references,
  176. and Laravel Route and Eloquent edges when the source shows explicit framework imports, model
  177. inheritance and receiver evidence. Static Laravel routes in `routes/*.php` emit Endpoint nodes
  178. and controller HANDLES edges, including literal group prefixes.
  179. Java projects get Spring dependency-injection call resolution, request endpoints and WebFlux routes, scheduled triggers, application-event publisher-to-listener edges, Spring AOP advice-to-target edges, and Temporal workflow and activity edges. Each resolver runs after the parse and needs the injected field, published event or workflow stub to be visible in the repository.
  180. </details>
  181. ### Add your own language
  182. <details>
  183. <summary><strong>Map a file extension to a bundled Tree-sitter grammar in <code>languages.toml</code></strong></summary>
  184. <br>
  185. If your repository uses a language the parser does not cover, add a `languages.toml` to `.code-review-graph/` that maps file extensions to any grammar bundled in `tree_sitter_language_pack`, plus the node types for functions, classes, imports and calls:
  186. ```toml
  187. [languages.erlang]
  188. extensions = [".erl"]
  189. grammar = "erlang"
  190. function_node_types = ["function_clause"]
  191. class_node_types = ["record_decl"]
  192. import_node_types = ["import_attribute"]
  193. call_node_types = ["call"]
  194. ```
  195. The generic tree-sitter walker does the extraction. Built-in languages cannot be overridden. See [docs/CUSTOM_LANGUAGES.md](docs/CUSTOM_LANGUAGES.md) for the schema, validation rules and a worked example.
  196. </details>
  197. ### Risk-scored PR reviews in CI (GitHub Action)
  198. <details>
  199. <summary><strong>One pull request comment with risk scores, affected flows and test gaps; see the sample workflow</strong></summary>
  200. <br>
  201. The same analysis runs as a composite GitHub Action. The graph is built and queried on your CI runner; no source code is sent to an external service. On each pull request the action posts one sticky comment with risk-scored functions, affected execution flows and test gaps, updated in place on every push. The optional `fail-on-risk` input turns it into a merge gate. The optional `details` input adds more graph context, folded away and capped in size: why each top symbol scored what it did, the communities, hubs and cross-boundary links the change touches, its impact radius, its untested hotspots, and where the graph came from.
  202. ```yaml
  203. # .github/workflows/code-review-graph.yml
  204. on:
  205. pull_request:
  206. permissions:
  207. contents: read
  208. pull-requests: write
  209. jobs:
  210. review:
  211. runs-on: ubuntu-latest
  212. steps:
  213. - uses: actions/checkout@v7
  214. - uses: tirth8205/code-review-graph@v2.4.0
  215. with:
  216. github-token: ${{ secrets.GITHUB_TOKEN }}
  217. ```
  218. See [docs/GITHUB_ACTION.md](docs/GITHUB_ACTION.md) for inputs, risk levels and caching, or the workflow this repository runs on itself in [`.github/workflows/pr-review.yml`](.github/workflows/pr-review.yml).
  219. </details>
  220. ---
  221. ## Benchmarks
  222. The median per-question token reduction across the 6 repositories is about **63x** (whole-corpus baseline vs graph query). The **358x** maximum is one repository (fastapi, the largest corpus), not the typical result.
  223. <details>
  224. <summary><strong>The benchmark board, and how the numbers were made</strong></summary>
  225. <br>
  226. <p align="center">
  227. <img src="diagrams/diagram5_benchmark_board.png" alt="Benchmarks across 6 repositories: ~63x median per-question token reduction (358x max), 0.69 average impact F1 against graph-derived ground truth" width="85%" />
  228. </p>
  229. All numbers come from the evaluation runner against 6 open-source repositories (13 commits). Every config pins an upstream SHA, Leiden runs with a fixed seed, and embeddings are deterministic on CPU, so two runs on different machines produce the same numbers. The reproduction recipe is in [`docs/REPRODUCING.md`](docs/REPRODUCING.md). A weekly report-only run on the two smallest configs lives in [`.github/workflows/eval.yml`](.github/workflows/eval.yml).
  230. </details>
  231. <details>
  232. <summary><strong>Token efficiency: ~63x median per-question reduction (range 35x to 358x; whole-corpus vs graph query)</strong></summary>
  233. <br>
  234. For a typical agent question (`"how does authentication work"`, `"what is the main entry point"`, and so on), the graph returns ~2,200 to 3,900 tokens of search hits plus neighbour edges instead of every source file. The table averages the 5 sample questions defined in `code_review_graph/token_benchmark.py`.
  235. | Repo | Snapshot SHA | naive_corpus_tokens | avg graph_tokens | Reduction |
  236. |------|---|-----------------:|----------------:|----------:|
  237. | fastapi | `22381558` | 948,793 | 2,653 | **357.6x** |
  238. | flask | `a29f88ce` | 143,594 | 2,196 | **65.4x** |
  239. | code-review-graph | `84bde354` | 208,821 | 3,190 | **65.5x** |
  240. | gin | `5c00df8a` | 166,868 | 2,766 | **60.3x** |
  241. | httpx | `b55d4635` | 142,356 | 2,661 | **53.5x** |
  242. | express | `b4ab7d65` | 136,052 | 3,936 | **34.6x** |
  243. > Captured 2026-08-02 from clean clones at the pinned SHAs (crg 2.3.7, local `all-MiniLM-L6-v2` embeddings). These numbers are lower than the 2026-05-25 capture they replace: node embedding text became richer, so `avg graph_tokens` rose in every repo. fastapi is measured at its current pin `22381558` rather than the retired `0227991a`.
  244. >
  245. > The Reduction column is `naive_corpus_tokens / avg graph_tokens`, so it divides out from the two columns beside it. The benchmark's own `average_reduction_ratio` averages the five per-question ratios instead, which always reads higher; those per-question figures are in [`docs/REPRODUCING.md`](docs/REPRODUCING.md#standalone-token-benchmark-code_review_graphtoken_benchmarkpy).
  246. >
  247. > The `code-review-graph` row is a snapshot, not a current measurement. The repository has grown since `84bde354`, so its corpus and graph are both much larger today.
  248. The whole-corpus baseline is an upper bound no real agent pays; an agent greps for identifiers and reads the best-matching files. The `agent_baseline` eval benchmark measures that case (a pure-Python grep over the corpus, top-3 files by match count, token-counted against the graph query cost). Against that realistic baseline the median across 18 questions on 6 repositories is **6.65x** (mean 14.8x, range 4.2x to 72.6x), captured 2026-09-22, before search and this baseline began ranking test files lower, so `code-review-graph eval --benchmark agent_baseline --embed` now gives different numbers until the capture is redone. The full table is in `docs/REPRODUCING.md`, under "Canonical capture, 2026-09-22".
  249. The ratio tracks repository size, because the graph answer stays flat (2,432 to 4,021 tokens across every repo measured) while the grep baseline grows with the corpus: 4.5x on express, 52x on fastapi. Both figures measure **retrieval** cost, the tokens needed to locate an answer. An agent that then opens the files the graph named pays the graph on top of its usual reads rather than instead of them; `semantic_search_nodes_tool(include_source=True)` returns the code with the locations so it does not have to, and measuring that path end-to-end is open work.
  250. The formal `token_efficiency` benchmark measures a different scenario, the full `get_review_context()` JSON against only the changed-file content of a commit, and reports ratios below 1 for small commits because the response carries impact-radius edges and source snippets. The two benchmarks answer different questions; see [`docs/REPRODUCING.md`](docs/REPRODUCING.md#which-benchmark-measures-what).
  251. Review and impact tools attach a compact `context_savings` estimate to their responses. The CLI shows the same figures in the `Token Savings` panel (see Usage below) and `--verify` compares them with OpenAI's `cl100k_base` tokenizer. Calibration across 222 sample files puts the estimate within about 1% of real tokens in aggregate ([data](docs/REPRODUCING.md#calibration-table)).
  252. </details>
  253. <details>
  254. <summary><strong>Impact accuracy: 0.69 average F1 against graph-derived ground truth (recall 1.0 is a circular upper bound)</strong></summary>
  255. <br>
  256. Blast-radius analysis recovers every file in the ground truth on all 13 evaluation commits. Read that as an upper bound, not as "100% recall": the ground truth (changed files plus files with call or import edges into them) comes from the same graph the predictor traverses. The lower precision is deliberate; flagging an extra file costs less than missing a broken dependency.
  257. | Repo | Commits | Avg F1 | Avg Precision | Recall (graph-derived upper bound) |
  258. |------|--------:|-------:|--------------:|-------:|
  259. | httpx | 2 | 0.863 | 0.785 | 1.0 |
  260. | code-review-graph | 2 | 0.734 | 0.584 | 1.0 |
  261. | fastapi | 2 | 0.697 | 0.539 | 1.0 |
  262. | express | 2 | 0.667 | 0.500 | 1.0 |
  263. | flask | 2 | 0.633 | 0.485 | 1.0 |
  264. | gin | 3 | 0.609 | 0.439 | 1.0 |
  265. | **Average** | **13** | **0.693** | **0.546** | **1.000** |
  266. This table is from the 2026-08-02 capture, taken before the path fix described below. That bug also kept real neighbour files out of the graph-derived ground truth, so these numbers will change when the benchmark is re-run.
  267. The benchmark also runs a **co-change mode**: the predictor is seeded with one changed file and graded against the other files the author touched in the same commit, which is evidence from git history rather than from the graph. Both modes appear in the result CSVs (`ground_truth_mode` column). In the 2026-08-02 capture co-change mode returned `predicted_files = 0` on every graded commit, code seeds included (for example `code_review_graph/cli.py` and gin's `context.go`). The cause was a path bug in the benchmark: `git diff` gives repo-relative paths, the graph stores absolute ones, so the seed never matched a node. That bug is now fixed, but the benchmark has not been re-run yet, so no co-change number is quoted.
  268. </details>
  269. <details>
  270. <summary><strong>Build stats</strong></summary>
  271. <br>
  272. From the same 2026-08-02 clean-room build at the pinned SHAs above. Embedding counts are lower than node counts because File nodes are not embedded. The `code-review-graph` row is that snapshot, not the repository as it stands now.
  273. | Repo | Nodes | Edges | Embeddings |
  274. |------|------:|------:|-----------:|
  275. | fastapi | 6,287 | 32,036 | 5,159 |
  276. | express | 1,990 | 19,492 | 1,849 |
  277. | gin | 1,589 | 17,237 | 1,491 |
  278. | code-review-graph | 1,446 | 9,094 | 1,354 |
  279. | flask | 1,415 | 8,259 | 1,329 |
  280. | httpx | 1,263 | 8,236 | 1,193 |
  281. </details>
  282. ### Limitations
  283. <details>
  284. <summary><strong>Five known limits: circular recall, small edits, search ranking, flow detection, false positives</strong></summary>
  285. <br>
  286. - **Impact "recall 1.0" is circular.** The historical ground truth comes from the same graph edges the predictor walks, so it is an upper bound by construction. Co-change numbers are not quoted until the benchmark is re-run with the path fix.
  287. - **Small single-file changes.** Graph context can exceed a plain file read for trivial edits. The overhead is the structural metadata that makes multi-file analysis possible.
  288. - **Search ranking.** Keyword search usually finds the right result near the top, but ranking needs work. Express queries can return no hits because of module-pattern naming.
  289. - **Flow detection.** Entry-point detection is strongest for Python and PHP/Laravel. JavaScript and Go flow detection needs work.
  290. - **Precision vs recall.** Impact analysis is conservative. It flags files that might be affected, which means false positives in large dependency graphs.
  291. </details>
  292. ---
  293. ## Features
  294. Updates, impact analysis, search, visualisation, CI reviews, refactoring and multi-repo support, all kept on your machine.
  295. <details>
  296. <summary><strong>The full feature table</strong></summary>
  297. <br>
  298. | Feature | Details |
  299. |---------|---------|
  300. | **Incremental updates** | Re-parses only files whose hash changed. On a ~3,000-file repo a two-file edit takes ~2.5 s on the hook path ([measured](docs/REPRODUCING.md#incremental-update-latency)). |
  301. | **Language and notebook support** | See [Language coverage](#language-coverage-and-notebooks) above. |
  302. | **Framework-aware PHP parsing** | Repository-bounded Composer PSR-4 imports, Blade template references, evidence-gated Laravel Route-to-controller and Eloquent relationship edges |
  303. | **Framework-aware Java parsing** | Spring dependency-injection call resolution, request endpoints and WebFlux routes, scheduled triggers, application-event publisher-to-listener edges, Spring AOP advice edges, Temporal workflow and activity edges, and Spring Boot config keys indexed without their values |
  304. | **Blast-radius analysis** | Which functions, classes and files are likely affected by a change |
  305. | **Auto-update hooks** | Editor hooks, git hooks (before each commit, after checkout, merge and rebase) and watch mode update the graph as you work |
  306. | **Semantic search** | Optional vector embeddings via sentence-transformers, Google Gemini, MiniMax, Voyage AI, or any OpenAI-compatible endpoint |
  307. | **Interactive visualisation** | D3.js force-directed graph with search, community legend toggles and degree-scaled nodes, plus a neighbourhood view seeded from a symbol, file, flow or change |
  308. | **Hub and bridge detection** | Most-connected nodes and chokepoints (betweenness centrality) |
  309. | **Surprise scoring** | Unexpected coupling: cross-community, cross-language, peripheral-to-hub edges |
  310. | **Knowledge gap analysis** | Isolated nodes, untested hotspots, thin communities, import cycles |
  311. | **Suggested questions** | Review questions generated from bridges, hubs and surprises |
  312. | **Edge confidence** | Four tiers (EXTRACTED, INFERRED, AMBIGUOUS, UNRESOLVED) with float scores on edges, so a call the graph could not bind says so |
  313. | **Graph traversal** | BFS/DFS from any node with configurable depth and token budget; `path_to` shows how one symbol reaches another and names the weakest hop |
  314. | **Export formats** | GraphML, Neo4j Cypher, Obsidian vault, JSON, and SVG (SVG needs matplotlib from the `eval` extra) |
  315. | **Token benchmarking** | `code_review_graph/token_benchmark.py` measures whole-corpus tokens against graph query tokens per question |
  316. | **Estimated context savings** | `context_savings` metadata (`estimated`, `saved_tokens`, `saved_percent`) on review, impact, detect-changes and architecture responses |
  317. | **Community auto-split** | Communities above 25% of the graph are split recursively with Leiden |
  318. | **Execution flows** | Call chains from entry points, sorted by weighted criticality |
  319. | **Community detection** | Leiden clustering with resolution scaled to graph size |
  320. | **Architecture overview** | Community-based architecture map with coupling warnings |
  321. | **Risk-scored reviews** | `detect_changes` maps diffs to affected functions, YAML and JSON paths, flows and test gaps |
  322. | **Custom languages** | New languages via `.code-review-graph/languages.toml`, no fork needed |
  323. | **GitHub Action** | Sticky risk-scored PR review comments in CI, with an optional `fail-on-risk` merge gate |
  324. | **Refactoring tools** | Rename preview, framework-aware dead code detection, community-driven suggestions |
  325. | **Wiki generation** | Markdown wiki from community structure |
  326. | **Multi-repo registry** | Register several repos and search across them |
  327. | **Multi-repo daemon** | `crg-daemon` watches several repos as child processes, with health checks and restart |
  328. | **MCP prompts** | 5 workflow templates: review, architecture, debug, onboard, pre-merge |
  329. | **Full-text search** | FTS5 hybrid search combining keyword and vector similarity |
  330. | **Local storage** | One SQLite file in `.code-review-graph/`; no external database or cloud service |
  331. </details>
  332. ---
  333. ## Usage
  334. Your assistant uses the graph by itself once it is built. Open a part below for skills, commands, MCP tools and settings.
  335. <details>
  336. <summary><strong>Skills</strong></summary>
  337. <br>
  338. `install` writes these four skills for the platforms it sets up that support them (Claude Code, Gemini CLI, CodeBuddy Code, Hermes Agent and Qoder). Ask for one by name.
  339. | Skill | Description |
  340. |-------|-------------|
  341. | `explore-codebase` | Navigate and understand codebase structure using the knowledge graph |
  342. | `review-changes` | Perform a structured code review using change detection and impact |
  343. | `debug-issue` | Systematically debug issues using graph-powered code navigation |
  344. | `refactor-safely` | Plan and execute safe refactoring using dependency analysis |
  345. Qoder also gets `build-graph`, `review-delta` and `review-pr` from the repository's `skills/` directory.
  346. </details>
  347. <details>
  348. <summary><strong>CLI reference</strong></summary>
  349. <br>
  350. ```bash
  351. code-review-graph install # Set up the AI coding tools found on this machine
  352. code-review-graph install --platform <name> # One platform
  353. code-review-graph install --steering # Claude Code: graph context beside each search and read
  354. code-review-graph uninstall --dry-run # Preview removal of installed artifacts
  355. code-review-graph doctor # Check copies, MCP entries, graph and hooks; changes nothing
  356. code-review-graph build # Parse the whole codebase
  357. code-review-graph build --follow-symlinks # Also index symlinked folders
  358. code-review-graph update # Incremental update (changed files only)
  359. code-review-graph status # Graph statistics
  360. code-review-graph watch # Update on file changes
  361. code-review-graph forget <path> # Drop already-parsed files from the graph
  362. code-review-graph dead-code # Functions and classes with no callers or tests
  363. code-review-graph query path_to <from> --to <to> # How one symbol reaches another
  364. code-review-graph impact --detail-level compact # Blast radius as ranked file paths
  365. code-review-graph visualize # Interactive HTML graph
  366. code-review-graph visualize --seed-symbol <name> # Neighbourhood of one symbol
  367. code-review-graph visualize --format json # Export graph data as JSON
  368. code-review-graph visualize --format graphml # Export as GraphML
  369. code-review-graph visualize --format svg # Export as SVG (needs matplotlib)
  370. code-review-graph visualize --format obsidian # Export as Obsidian vault
  371. code-review-graph visualize --format cypher # Export as Neo4j Cypher
  372. code-review-graph wiki # Markdown wiki from communities
  373. code-review-graph detect-changes --brief # Top 3 to review, risk + token savings (read-only)
  374. code-review-graph detect-changes --brief --base main # Against the merge base of main and HEAD
  375. code-review-graph update --brief # Refresh graph + same panel
  376. code-review-graph detect-changes --brief --verify # Cross-check against tiktoken
  377. code-review-graph detect-changes --details all # Add graph context to the JSON
  378. code-review-graph context-history # Trend of the opt-in savings log (CRG_CONTEXT_HISTORY=1)
  379. code-review-graph register <path> # Register repo in the multi-repo registry
  380. code-review-graph unregister <path|alias> # Remove repo from the registry
  381. code-review-graph repos # List registered repositories
  382. code-review-graph daemon start # Start the multi-repo watch daemon
  383. code-review-graph daemon stop # Stop the daemon
  384. code-review-graph daemon status # Daemon status and repos
  385. code-review-graph eval --all # Run every evaluation benchmark
  386. code-review-graph serve # Start the MCP server (stdio)
  387. code-review-graph serve --http # MCP over Streamable HTTP on localhost:5555
  388. code-review-graph serve --http --multi-repo # One HTTP server for every registered repo
  389. code-review-graph serve --multi-worktree # One child server per linked Git worktree
  390. ```
  391. This is a selection. `code-review-graph` with no command lists every command, in groups, and [docs/COMMANDS.md](docs/COMMANDS.md) documents their flags. A mistyped command exits 2 and suggests the closest one.
  392. When `detect-changes --base` names a branch, the diff runs against the merge base of that branch and HEAD. Commit hashes and other revisions are used as given. A base git does not know stops with exit code 1 and says how to check it. In a repository with one commit or none, the default base reviews uncommitted and new files instead, and says so.
  393. `visualize --format svg` needs matplotlib, which ships in the `eval` extra (`pip install "code-review-graph[eval]"`). The other export formats need no extra install.
  394. JSON exports are written inside the local graph data directory, which Git ignores by default. They can contain absolute paths and code-structure metadata, so inspect an export before publishing it.
  395. </details>
  396. <details>
  397. <summary><strong>Token Savings panel: <code>detect-changes --brief</code> vs <code>update --brief</code></strong></summary>
  398. <br>
  399. Both commands print the same panel showing how many tokens the graph saved compared with handing the changed files to an agent raw. They differ in one thing: whether the graph is refreshed first. Above the panel, `detect-changes --brief` also lists up to three things to review first, each with its file and line, its risk out of 1.00, its callers and its tests.
  400. ```text
  401. ┌─────────────────────── Token Savings ────────────────────────┐
  402. │ Full context would be: 12,921 tokens │
  403. │ Graph context used: 762 tokens │
  404. │ Saved: 12,159 tokens (~94%) │
  405. │ Breakdown: Functions 244 · Tests 191 · Risk 244 · Other 83 │
  406. └──────────────────────────────────────────────────────────────┘
  407. ```
  408. | Command | What it does | When to use |
  409. |---|---|---|
  410. | `detect-changes --brief` | Read-only. Queries the existing graph for the current changes and prints the panel. | Most of the time; hooks or `crg-daemon` keep the graph fresh. |
  411. | `update --brief` | Re-parses the changed files into the graph first, then prints the same panel. | After a rebase, a large change set, or whenever the graph may be stale. |
  412. Add `--verify` to either command to compare the figures with OpenAI's `cl100k_base` tokenizer (needs `pip install tiktoken`). The estimate is within about 1% of real tokens in aggregate; see [`docs/REPRODUCING.md`](docs/REPRODUCING.md#calibration-table).
  413. The same `context_savings` metadata is attached to the JSON responses of the `get_impact_radius`, `get_review_context`, `detect_changes` and `get_architecture_overview` MCP tools.
  414. To see these estimates over time, set `CRG_CONTEXT_HISTORY=1` (off by default). Each estimate then adds one line to a local log next to `graph.db`, holding token counts, tool names, a timestamp, a detail level and file and depth counts, never file names, paths or source text, and `code-review-graph context-history` prints it per day or per tool. See [docs/USAGE.md](docs/USAGE.md#context-history).
  415. </details>
  416. <details>
  417. <summary><strong>Multi-repo daemon</strong></summary>
  418. <br>
  419. If `install` gives your editor no hooks (for example Windsurf or Zed), or you want the graph kept fresh without editor integration, the daemon watches your repositories and updates their graphs. It ships with `code-review-graph`; no separate install.
  420. ```bash
  421. # 1. Register the repos to watch
  422. crg-daemon add ~/project-a --alias proj-a
  423. crg-daemon add ~/project-b
  424. # 2. Start the daemon (runs in the background)
  425. crg-daemon start
  426. # 3. Check on it
  427. crg-daemon status # daemon and per-repo watcher status
  428. crg-daemon logs --repo proj-a -f # tail logs for one repo
  429. crg-daemon stop # stop the daemon and all watchers
  430. ```
  431. Also available as `code-review-graph daemon start|stop|status|...`.
  432. `crg-daemon add` writes to `~/.code-review-graph/watch.toml`, which you can also edit directly:
  433. ```toml
  434. [[repos]]
  435. path = "/home/user/project-a"
  436. alias = "proj-a"
  437. [[repos]]
  438. path = "/home/user/project-b"
  439. alias = "project-b"
  440. ```
  441. The daemon watches this file and starts or stops watcher processes as repos are added or removed. A health check every 30 seconds restarts dead watchers.
  442. See [docs/COMMANDS.md](docs/COMMANDS.md#standalone-daemon-cli-crg-daemon) for the full config reference.
  443. </details>
  444. <details>
  445. <summary><strong>30 MCP tools</strong></summary>
  446. <br>
  447. The assistant uses these once the graph is built. The 25 tools that only read carry `readOnlyHint: true`, so a client can run them without asking; the five that write (`build_or_update_graph_tool`, `run_postprocess_tool`, `embed_graph_tool`, `apply_refactor_tool`, `generate_wiki_tool`) do not.
  448. | Tool | Description |
  449. |------|-------------|
  450. | `build_or_update_graph_tool` | Build or incrementally update the graph |
  451. | `run_postprocess_tool` | Re-run flow detection, community detection and FTS indexing |
  452. | `get_minimal_context_tool` | Compact context (~100 tokens); call this first |
  453. | `get_impact_radius_tool` | Blast radius of changed files; `detail_level="compact"` gives ranked file paths |
  454. | `get_review_context_tool` | Review context with structural summary |
  455. | `query_graph_tool` | Callers, callees, tests, imports, inheritance, and `path_to` between two symbols |
  456. | `traverse_graph_tool` | BFS/DFS traversal from any node with a token budget |
  457. | `semantic_search_nodes_tool` | Search code entities by name or meaning |
  458. | `embed_graph_tool` | Compute vector embeddings for semantic search |
  459. | `list_graph_stats_tool` | Graph size and health |
  460. | `get_docs_section_tool` | Retrieve documentation sections |
  461. | `find_large_functions_tool` | Functions, classes or files above a line-count threshold |
  462. | `list_flows_tool` | Execution flows sorted by criticality |
  463. | `get_flow_tool` | One execution flow |
  464. | `get_affected_flows_tool` | Flows affected by changed files |
  465. | `list_communities_tool` | Detected code communities |
  466. | `get_community_tool` | One community |
  467. | `get_architecture_overview_tool` | Architecture overview from community structure |
  468. | `detect_changes_tool` | Risk-scored change impact analysis |
  469. | `get_hub_nodes_tool` | Most-connected nodes |
  470. | `get_bridge_nodes_tool` | Chokepoints by betweenness centrality |
  471. | `get_knowledge_gaps_tool` | Structural weaknesses, untested hotspots and import cycles |
  472. | `get_surprising_connections_tool` | Unexpected cross-community coupling |
  473. | `get_suggested_questions_tool` | Review questions generated from the analysis |
  474. | `refactor_tool` | Rename preview, dead code detection, suggestions |
  475. | `apply_refactor_tool` | Apply a previously previewed refactoring |
  476. | `generate_wiki_tool` | Markdown wiki from communities |
  477. | `get_wiki_page_tool` | One wiki page |
  478. | `list_repos_tool` | Registered repositories |
  479. | `cross_repo_search_tool` | Search registered repositories; `repos` limits the search to a subset |
  480. **MCP prompts** (5 workflow templates):
  481. `review_changes`, `architecture_map`, `debug_issue`, `onboard_developer`, `pre_merge_check`
  482. </details>
  483. <details>
  484. <summary><strong>Configuration</strong></summary>
  485. <br>
  486. To exclude paths from indexing, create a `.code-review-graphignore` file in the repository root:
  487. ```
  488. generated/**
  489. *.generated.ts
  490. vendor/**
  491. node_modules/**
  492. ```
  493. In git repositories a build reads tracked files plus untracked files git does not ignore (`git ls-files` and `git ls-files --others --exclude-standard`), so gitignored files are skipped. Use `.code-review-graphignore` to exclude other files or when git is not available. The default ignore list is in [docs/USAGE.md](docs/USAGE.md#ignore-patterns).
  494. Optional dependency groups:
  495. ```bash
  496. pip install "code-review-graph[embeddings]" # Local vector embeddings (sentence-transformers)
  497. pip install "code-review-graph[google-embeddings]" # Google Gemini embeddings
  498. pip install "code-review-graph[communities]" # Community detection (igraph)
  499. pip install "code-review-graph[enrichment]" # Python call resolution with Jedi (then build --enrich)
  500. pip install "code-review-graph[eval]" # Evaluation benchmarks and SVG export (matplotlib)
  501. pip install "code-review-graph[wiki]" # ollama client (not used by the current wiki generator)
  502. pip install "code-review-graph[all]" # All optional dependencies
  503. ```
  504. ### Environment Variables
  505. | Variable | Description | Default |
  506. |----------|-------------|---------|
  507. | `CRG_GIT_TIMEOUT` | Timeout in seconds for Git operations (build, update, watch) | `30` |
  508. | `CRG_DISCOVERY_TIMEOUT` | Timeout in seconds for each Git command that discovers what changed, when a review tool or command was not given an explicit file list. Running out reports an error, never "no changes" | `5`, or `CRG_GIT_TIMEOUT` when you set that explicitly |
  509. | `CRG_DATA_DIR` | Directory for graph databases and generated artefacts. `install`'s record of the files it wrote stays in `.code-review-graph/` in the repository | - |
  510. | `CRG_HOME` | Folder for per-user state: the multi-repo registry (`registry.json`), the daemon's `watch.toml`, its pid and state files, and `logs/` | `~/.code-review-graph` |
  511. | `CRG_HOOK_WORKTREES` | Set to `1` to let the generated git hooks run in linked git worktrees | - |
  512. | `CRG_EMBEDDING_MODEL` | Default model for local vector embeddings | `all-MiniLM-L6-v2` |
  513. | `CRG_ACCEPT_CLOUD_EMBEDDINGS` | Set to `1` to suppress the cloud embedding egress warning | - |
  514. | `CRG_ALLOW_REMOTE_CODE` | Allow HuggingFace models that require `trust_remote_code=True` | `0` |
  515. | `CRG_VECTOR_CACHE` | Set to `1` to keep the decoded embedding vectors in memory between semantic searches instead of reading them all back from SQLite on every query. Costs RAM (vectors × dimensions × 4 bytes per cached index) and one open read connection per cached database for the life of the process: on Windows, `graph.db` cannot be deleted or replaced while it is open | - |
  516. | `CRG_MAX_IMPACT_NODES` | Maximum nodes in impact analysis | `500` |
  517. | `CRG_MAX_IMPACT_DEPTH` | Search depth for blast-radius analysis | `2` |
  518. | `CRG_MAX_BFS_DEPTH` | Maximum depth for graph traversal | `15` |
  519. | `CRG_MAX_CHANGED_FUNCS` | Maximum changed functions analysed in one change report | `500` |
  520. | `CRG_MAX_DELETION_FILES` | Maximum files whose old version is read in one change report, to name the functions and classes a diff deleted | `100` |
  521. | `CRG_MAX_CHANGED_YAML_PATHS` | Maximum changed YAML paths analysed in one change report, and separately the same number of JSON paths | `200` |
  522. | `CRG_MAX_TRANSITIVE_FRONTIER` | Maximum callees followed per hop when `tests_for` and `detect-changes` look for tests. The first by name are kept, so one graph always gives one answer | `50` |
  523. | `CRG_CALLER_TEST_ROUTE_DEPTH` | Hops to walk up incoming `CALLS` when looking for a tested caller of an untested changed symbol. Reported as a note, never as coverage | `2` |
  524. | `CRG_CALLER_TEST_ROUTE_MAX_CALLERS` | Maximum callers examined while looking for that tested caller | `500` |
  525. | `CRG_TOOL_TIMEOUT` | Timeout in seconds for read-only MCP tools (`0` disables). Does not bound the tools that write: build, postprocess, embed, wiki and apply-refactor | `0` |
  526. | `CRG_CHURN_WINDOW_DAYS` | Window for `detect-changes --churn` commit counts | `90` |
  527. | `CRG_CONTEXT_HISTORY` | Set to `1` to keep a local log of each `context_savings` estimate in `.code-review-graph/context-history.jsonl`; read it with `code-review-graph context-history`. Holds token counts, tool names, a timestamp, a detail level and file and depth counts, never file names, paths or source text, and is never sent anywhere | - |
  528. | `CRG_LEIDEN_SEED` | Seed for Leiden community detection | `42` |
  529. | `CRG_RECURSE_SUBMODULES` | Include git submodules when set to `1`, `true` or `yes` | - |
  530. | `CRG_FOLLOW_SYMLINKS` | Follow symlinked folders, inside or outside the repository, when set to `1`, `true`, `yes` or `on`; same as `--follow-symlinks`. See [Symlinked folders](docs/USAGE.md#symlinked-folders) | - |
  531. | `CRG_MAX_FOLLOWED_FILES` | Most files taken through followed symlinked folders | `10000` |
  532. | `CRG_TOOLS` | Comma-separated allowlist of MCP tools to expose when serving | - |
  533. | `CRG_READ_ONLY` | Set to `1` (or `true`, `yes`, `on`) to open the graph read-only. Nothing in the data folder is created, upgraded or logged, and commands that write fail. The Codex skill's read-only CLI sets it | - |
  534. | `CRG_BIN` | The `code-review-graph` program the Codex skill's read-only CLI runs, when it has another name or is not on PATH | the one on PATH |
  535. | `GOOGLE_API_KEY` | API key for Google Gemini embeddings | - |
  536. | `MINIMAX_API_KEY` | API key for MiniMax embeddings | - |
  537. | `VOYAGE_API_KEY` | API key for Voyage embeddings | - |
  538. | `CRG_VOYAGE_MODEL` | Model for Voyage embeddings | `voyage-code-3` |
  539. | `CRG_VOYAGE_OUTPUT_DIMENSION` | Output dimension for Voyage embeddings | `1024` |
  540. | `CRG_VOYAGE_OUTPUT_DTYPE` | Output dtype for Voyage embeddings | `float` |
  541. | `CRG_VOYAGE_BASE_URL` | Voyage embeddings endpoint | `https://api.voyageai.com/v1` |
  542. | `CRG_VOYAGE_BATCH_SIZE` | Batch size for Voyage requests | `100` |
  543. | `CRG_VOYAGE_MIN_INTERVAL_SEC` | Minimum delay between Voyage requests | `0` |
  544. | `CRG_OPENAI_BASE_URL` | OpenAI-compatible embeddings endpoint | - |
  545. | `CRG_OPENAI_API_KEY` | API key for OpenAI-compatible embeddings | - |
  546. | `CRG_OPENAI_MODEL` | Model for OpenAI-compatible embeddings | - |
  547. | `CRG_OPENAI_DIMENSION` | Pin the embedding dimension (v3 models support reduction) | - |
  548. | `CRG_OPENAI_BATCH_SIZE` | Batch size for OpenAI-compatible requests | `100` |
  549. | `NO_COLOR` | Disable ANSI colours in the terminal | - |
  550. | `CRG_SERIAL_PARSE` | Set to `1` to disable parallel parsing (for debugging) | - |
  551. | `CRG_ENABLE_ENRICHMENT` | Set to `1` to resolve Python method calls with Jedi on every build and update (needs the `enrichment` extra; about a second more per Python file). Same as `build --enrich` | off |
  552. | `CRG_DISABLE_ENRICHMENT` | Set to `1` to never run Jedi, even when asked for | - |
  553. OpenAI-compatible embeddings need no extra install. Set the variables and pass `provider="openai"` to `embed_graph`:
  554. ```bash
  555. export CRG_OPENAI_BASE_URL=http://127.0.0.1:3000/v1 # or https://api.openai.com/v1
  556. export CRG_OPENAI_API_KEY=sk-...
  557. export CRG_OPENAI_MODEL=text-embedding-3-small # whatever your gateway serves
  558. # optional:
  559. export CRG_OPENAI_DIMENSION=1536 # pin dim (v3 models support reduction)
  560. export CRG_OPENAI_BATCH_SIZE=100 # lower for gateways with tight limits
  561. ```
  562. The cloud-egress warning is skipped when the base URL points at localhost (`127.0.0.1`, `localhost`, `0.0.0.0`, `::1`).
  563. Voyage embeddings need no extra install. Set `VOYAGE_API_KEY` and pass `provider="voyage"` to `embed_graph`; the default model is `voyage-code-3`:
  564. ```bash
  565. export VOYAGE_API_KEY=pa-...
  566. export CRG_ACCEPT_CLOUD_EMBEDDINGS=1
  567. code-review-graph embed --provider voyage --model voyage-code-3
  568. ```
  569. > **Model selection.** Avoid `-preview`, `-beta` or `-exp` model IDs for an index you plan to keep; preview models can change weights (a different dimension forces a full re-embed) or be withdrawn. Prefer GA releases such as `text-embedding-3-small` / `text-embedding-3-large` (OpenAI) or `gemini-embedding-001` (native Gemini provider, which needs `GOOGLE_API_KEY`).
  570. >
  571. > The embedding text is identifiers, signatures, structural context, and a bounded first-paragraph docstring or doc-comment summary. Function bodies are not sent. Graphs created before documentation extraction was added need one full `code-review-graph build` before re-embedding. Routine builds never refresh embeddings; to refresh after a build, pass both `--embedding-provider` and `--embedding-model`. Cloud providers receive this source-derived text and may charge for it.
  572. #### Tool Filtering
  573. CRG exposes 30 MCP tools by default. To limit the server to a subset, use `--tools` or the `CRG_TOOLS` environment variable:
  574. ```bash
  575. # CLI flag
  576. code-review-graph serve --tools query_graph_tool,semantic_search_nodes_tool,detect_changes_tool
  577. # Environment variable
  578. CRG_TOOLS=query_graph_tool,semantic_search_nodes_tool code-review-graph serve
  579. ```
  580. The flag takes precedence over the variable. When neither is set, all tools are available. In an MCP client config:
  581. ```json
  582. {
  583. "mcpServers": {
  584. "code-review-graph": {
  585. "command": "code-review-graph",
  586. "args": ["serve", "--tools", "query_graph_tool,semantic_search_nodes_tool,detect_changes_tool,get_review_context_tool"]
  587. }
  588. }
  589. }
  590. ```
  591. </details>
  592. ### Run with Docker or Podman
  593. <details>
  594. <summary><strong>Build the image from a release, then run it on your repository</strong></summary>
  595. <br>
  596. No image is published. Build one from a release tag; a plain clone gives the `staging` branch, which can hold changes not yet released:
  597. ```bash
  598. git clone --branch v2.4.0 https://github.com/tirth8205/code-review-graph.git
  599. cd code-review-graph
  600. docker build -t code-review-graph:local .
  601. ```
  602. From the repository you want to analyse, run:
  603. ```bash
  604. docker run --rm \
  605. --user "$(id -u):$(id -g)" \
  606. --env HOME=/tmp \
  607. --volume "$PWD:/workspace" \
  608. code-review-graph:local build
  609. ```
  610. The mounted repository must be writable. The command above uses your
  611. user and group IDs so the generated `.code-review-graph/` directory
  612. remains owned by your user. Run these commands as a non-root host user.
  613. For Podman, build the same Dockerfile from the same clone and preserve your user mapping:
  614. ```bash
  615. podman build -t code-review-graph:local .
  616. podman run --rm \
  617. --userns=keep-id \
  618. --env HOME=/tmp \
  619. --volume "$PWD:/workspace" \
  620. code-review-graph:local build
  621. ```
  622. The graph persists in `.code-review-graph/` in the mounted repository and stores
  623. absolute container paths such as `/workspace/app.py`. Run `update` and
  624. `detect-changes` through Docker or Podman with the same `/workspace` mount.
  625. A host `update` on this graph can fail with "built with a different repository
  626. root". To switch to host commands, run `code-review-graph build` on the host
  627. to rebuild the graph with host paths.
  628. Replace `build` with `status` to inspect the saved graph.
  629. The image includes Git and defaults to a non-root user.
  630. No graph is generated during image construction.
  631. These examples use macOS/Linux shell syntax. On macOS, start your
  632. Docker-compatible engine or Podman machine before running them. On a host with
  633. SELinux on, such as Fedora, add `:z` to the mount (`"$PWD:/workspace:z"`), or
  634. the container is refused access to the repository.
  635. </details>
  636. ---
  637. ## FAQ and comparisons
  638. Answers in [docs/FAQ.md](docs/FAQ.md):
  639. <details>
  640. <summary><strong>How it compares with LSP, RAG and grep, when not to use it, and more</strong></summary>
  641. <br>
  642. - [vs LSP / language servers](docs/FAQ.md#how-is-this-different-from-lsp-and-language-servers): one persistent cross-language graph instead of per-language daemons; LSP stays more precise per symbol.
  643. - [vs RAG / embeddings](docs/FAQ.md#isnt-this-just-rag): structural edges parsed from the AST, not similarity chunks; embeddings are optional and only assist search.
  644. - [vs grep / agentic search](docs/FAQ.md#why-not-just-grep): grep wins on one-hop lookups; the graph wins on multi-hop questions (impact radius, callers-of-callers, tests-for, affected flows).
  645. - [When not to use it](docs/FAQ.md#when-should-i-not-use-it): small repos, trivial single-file diffs, one-off questions.
  646. - [Does it phone home?](docs/FAQ.md#does-it-phone-home): no telemetry; cloud embeddings are opt-in.
  647. - [How do I verify it is working?](docs/FAQ.md#how-do-i-verify-it-is-working): `status`, `detect-changes --brief`, `/mcp`.
  648. </details>
  649. ## Troubleshooting
  650. Start with `code-review-graph doctor`, above all when your AI tool says the graph was "written by a newer code-review-graph". It lists every copy on PATH, the version each MCP entry and hook runs, and the state of the graph. It changes nothing, exits 1 when a check fails, and takes `--json`.
  651. More cases, including Windows/WSL, are in [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).
  652. ### `pip` / `pipx` cannot download `hatchling` (or `Errno 9` / `Bad file descriptor` to PyPI)
  653. <details>
  654. <summary><strong>How to fix it</strong></summary>
  655. <br>
  656. Installing from a source tree (for example `pipx install .`) needs build dependencies from PyPI. If you see `Could not find a version that satisfies the requirement hatchling` after connection warnings, the Python in that terminal may not be able to open an HTTPS connection to `pypi.org`. This is seen most often in an editor's integrated terminal, and sometimes with a VPN, firewall or proxy.
  657. 1. Run the same command from a terminal outside the editor, such as Terminal.app.
  658. 2. Install from a checkout with [uv](https://docs.astral.sh/uv/), which uses different download machinery:
  659. ```bash
  660. cd /path/to/code-review-graph
  661. uv tool install . --force
  662. ```
  663. 3. For development in a clone, use `uv sync` and `uv run code-review-graph ...`.
  664. To diagnose: `python3 scripts/diagnose_pypi_connectivity.py`. If it prints `FAILED`, the problem is the network environment, not the package name.
  665. </details>
  666. ### Windows: `Invalid JSON: EOF while parsing` or `MCP error -32000: Connection closed`
  667. <details>
  668. <summary><strong>How to fix it</strong></summary>
  669. <br>
  670. Do not use a `cmd /c` wrapper in the Claude Code config. Point `~/.claude.json` at the `.exe` directly and set UTF-8 through the config:
  671. ```json
  672. "code-review-graph": {
  673. "command": "C:\\path\\to\\your\\venv\\Scripts\\code-review-graph.exe",
  674. "args": ["serve", "--repo", "C:\\path\\to\\your\\project"],
  675. "env": { "PYTHONUTF8": "1" }
  676. }
  677. ```
  678. </details>
  679. ## Contributing
  680. Pull requests target `staging` (the default branch). Changes are promoted
  681. `staging` → `testing` → `main`, and releases are tagged from `main`. No
  682. promotion is automatic: a person reviews and merges each one. See
  683. [CONTRIBUTING.md](CONTRIBUTING.md#branching-and-promotion) for the full flow.
  684. <details>
  685. <summary><strong>Set up a development copy and run the tests</strong></summary>
  686. <br>
  687. ```bash
  688. git clone https://github.com/tirth8205/code-review-graph.git
  689. cd code-review-graph
  690. python3 -m venv .venv && source .venv/bin/activate
  691. pip install -e ".[dev]"
  692. pytest
  693. ```
  694. </details>
  695. <details>
  696. <summary><strong>Add a built-in language</strong></summary>
  697. <br>
  698. To add a built-in language, edit `code_review_graph/parser.py`: add the extension to `EXTENSION_TO_LANGUAGE` and node type mappings to `_CLASS_TYPES`, `_FUNCTION_TYPES`, `_IMPORT_TYPES` and `_CALL_TYPES`. Include a test fixture and open a PR. For a language you only need in one repository, use [`languages.toml`](docs/CUSTOM_LANGUAGES.md) instead.
  699. </details>
  700. ## Licence
  701. MIT. See [LICENSE](LICENSE).
  702. <p align="center">
  703. <br>
  704. <a href="https://code-review-graph.com">code-review-graph.com</a><br><br>
  705. <code>pip install code-review-graph && code-review-graph install</code>
  706. </p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.