Stop Making Claude/Codex Repeatedly Scan Your Repo: This Tool Shows AI a Code Map First

AI Programming Claude Code Codex Code Review Code Knowledge Graph
发布于 2026-07-06 02:45:42 2 次浏览

Stop Making Claude/Codex Repeatedly Scan Your Repo: This Tool Shows AI a Code Map First

When you use AI to modify code, the most token-consuming part is often not "writing code." It's that before modifying, it doesn't know where to look. You just changed an interface, and it might first read middleware, models, config, utils; you just asked it to review a PR, and it might scan many unrelated files in the same directory. For small projects, it's fine. For large projects, monorepo, and legacy systems, this problem quickly spirals out of control. Recently I checked out a GitHub project: code-review-graph. Many online introductions call it a "token-saving tool," but I think that label isn't accurate enough. It's more like: installing a local code map for AI coding assistants. It first uses Tree-sitter to parse your repository, extracting functions, classes, imports, call relationships, inheritance, and test relationships, storing them in a local SQLite graph database. Then MCP clients like Claude Code, Cursor, Codex, Copilot can query the graph first before deciding which files to read. In other words, AI no longer "blindly reads the entire repo" upfront. Instead, it first asks: Who calls this function? Which modules will be affected if this file is changed? Where are the related tests? Which call chains are within the risk radius? How much context can this change roughly save? This is where it gets really interesting.

The Most Token-Wasting Part of AI Coding Has Finally Been Addressed

The traditional context retrieval approach for AI code review is crude: See the diff. Guess relevant files. Read a bunch of source code. Then start analyzing. Sounds fine. But in reality, it's often silly. You ask AI to look at an interface change, and it might flip through the entire directory; you ask it to judge whether a function has side effects, and it might first read a bunch of configs, utility classes, and test fixtures. It's not lazy—it's even too diligent. The problem is, diligence doesn't equal effectiveness. code-review-graph changes the order: Build the graph first. After changing code, query the impact radius. Only hand over the necessary functions, callers, tests, and risk summaries to AI. Then let AI read the minimum necessary files. The numbers reported by official and third-party articles aren't exactly consistent: early articles often mention 6.8x, 8.2x, up to 49x; the current PyPI/README gives 38x to 528x measured by "full-repo Q&A vs graph query." Don't take these numbers as absolute promises—they were measured under different scenarios. But the direction is clear: The larger the repo, the more complex the dependencies, the easier it is to save. No, to be precise, it's not just about saving. It's about reading less noise. This distinction is crucial. Because longer context doesn't equal higher quality context. If you feed AI a bunch of unrelated files, it's not only more expensive but also more likely to be misled.

Most Notably: The Graph Updates After Code Changes

This point is more important than "build the graph once after installation." Because if the code graph isn't updated, it becomes an outdated map. AI querying old call chains might even mislead decisions. code-review-graph uses incremental updates. First full repository parsing:

code-review-graph build

Re-parse only the changed files:

code-review-graph update

If you agreed to inject graph instructions during installation and the hooks are already written into .claude/settings.json or the corresponding client configuration, the graph will automatically update after file changes. So in daily use, you don't necessarily need to manually run watch. watch / daemon are more suitable for scenarios without hooks or when you want to monitor multiple repositories in the background. The official release also distinguishes two very practical commands. Read only the current changes and output the risk panel and token savings based on the existing graph:

code-review-graph detect-changes --brief

First refresh the changed files into the graph, then output the same analysis panel:

code-review-graph update --brief

Simple understanding: Daily development: detect-changes --brief is enough. Just rebased, made major changes, or suspect the graph is outdated: use update --brief. Long-term use: ensure hooks and graph instructions are written into the agent configuration. This turns the AI code modification workflow into: Make a small change. Refresh the graph. Check the impact radius. Let AI read only the necessary context. Then decide where to modify next. This is far more reliable than "let AI grep everywhere on its own." And it's very realistic. Because when we use AI to change code, what we fear most is not that it can't write a function, but that it doesn't know which parts it shouldn't touch.

How to Get Started? Don't Miss the Initialization

The current latest version on PyPI is 2.3.5, released on May 25, 2026. Installation is just the first step:

pip install code-review-graph

The real crucial part is initialization. Some tutorials directly mention install, but when you actually run it, you'll see an initialization flow like code-review-graph init / code-review-graph install. It doesn't just install the package—it configures the MCP server into your AI tools. For example, one initialization might automatically check and configure: Codex, Claude Code, Cursor, Zed, Continue, OpenCode, Antigravity, Qwen Code, Kiro. It also generates or modifies these items:

  • .mcp.json / MCP configurations for each client
  • The code-review-graph skill under .claude/skills
  • .claude/settings.json hooks
  • git pre-commit hook
  • Rule files like .cursorrules, .windsurfrules, Kiro steering, etc.
  • .code-review-graph/ in .gitignore This step is easily overlooked. But it precisely determines whether Claude Code / Codex will "prioritize querying the graph" later. Because at the end of initialization, it asks: Do you want to inject graph instructions into these rule files? Once you agree, the AI client doesn't just get an MCP tool—it gets a clear working habit: When exploring code, reviewing diffs, and determining impact scope, first use code-review-graph, then read the files. This is where this tool truly enters your daily workflow. After initialization, build the knowledge graph:
code-review-graph build

If you only want to configure a specific tool:

code-review-graph install --platform codex
code-review-graph install --platform cursor
code-review-graph install --platform claude-code
code-review-graph install --platform copilot

Common commands are also simple:

code-review-graph status
code-review-graph update
code-review-graph visualize
code-review-graph wiki
code-review-graph detect-changes --brief
code-review-graph serve

AI clients also have slash commands:

/code-review-graph:build-graph
/code-review-graph:review-delta
/code-review-graph:review-pr

If you just want to try it out, I suggest starting with the minimal loop:

pip install code-review-graph
code-review-graph init
code-review-graph build
code-review-graph detect-changes --brief

If your current version doesn't have init, use:

code-review-graph install

The key is not the command names. The key is to confirm three things: the MCP server is configured, graph instructions are written into the agent rules, and the graph has been built. Missing any one of these will reduce the effectiveness. Don't rush to plug it into every workflow. Run a review delta once, and see if the impact radius, related tests, and risk warnings it provides are reliable. If they are, then keep it in your daily agent configuration. Otherwise, it easily becomes a tool hoarding habit. Yeah, developers know what I mean.

Recommended Usage

If you've already run code-review-graph init and agreed to inject graph instructions into the agent rules, you don't need to write complex prompts every time. Just say normally:

Help me fix this bug.

Or:

Review this PR.

Or:

Check where this function change will affect.

Claude Code / Codex / Cursor will theoretically query the graph first:

  • Explore code: use semantic_search_nodes or query_graph first
  • See impact scope: use get_impact_radius first
  • Do code review: use detect_changes + get_review_context first
  • Look up call relationships: use query_graph with callers_of / callees_of / imports_of / tests_for
  • View architecture: use get_architecture_overview + list_communities Only when the graph coverage is insufficient, fallback to Grep / Glob / Read. So the most comfortable aspect of this tool is not "you memorize a few more commands." It's that after initialization, it changes AI's default working habit: Check the map first, then read the source code. This is critically important. In the past, we only looked at the final code diff produced by AI, but didn't check what context it had read beforehand. As a result, it might make an apparently correct fix based on the wrong scope. Even worse, you don't know where it went wrong. With the graph, at least AI will first "audit the map" according to rules. If the map doesn't cover it, it falls back to traditional file reading. Don't let it drive with its eyes closed.

What Projects Is It Suitable For?

Suitable for:

  • monorepo
  • Medium to large backend projects
  • Legacy projects maintained by multiple people
  • Teams that frequently use AI to review PRs
  • Projects that often modify public functions, base components, and interface layers
  • People who want to control token costs of Claude/Codex/Cursor Not suitable for:
  • Small projects with a few dozen files
  • Single-file scripts
  • Projects with heavy dynamic calls, reflection, plugin systems
  • Teams unwilling to maintain graph freshness Third-party articles also repeatedly mention a limitation: it is a static structure graph, not the runtime truth. Dynamic routing, configuration-driven behavior, cross-service calls, reflection, and runtime injection may exceed the graph's capabilities. So it is not a substitute for tests, nor a substitute for human review. Its positioning should be: the context router for AI coding assistants. That positioning is quite accurate. It is not responsible for judging all business logic, nor for proving that the code is definitely correct. It is responsible for telling AI, before it starts reading code: where you most likely should begin reading. Like a navigation system. Navigation doesn't drive for you. But without navigation, driving in an unfamiliar city really makes you dizzy to the point of breakdown.

Conclusion

The next phase of AI coding is not simply about giving models longer context. Long context is useful, but it also brings higher costs and lower signal-to-noise ratio. A smarter approach is: first structure the codebase, then let AI index through the graph. That's exactly what code-review-graph does: Build a local graph. Update incrementally. Check impact radius. Output minimal context. Let AI read less irrelevant code and focus more on truly risky areas. The real token saving is not about asking AI fewer questions. It's about stopping it from repeatedly reading files it shouldn't. If you're already using Claude Code, Codex, or Cursor to modify large repos, I recommend you try it at least once. Not to chase a new tool. But to see: among the tokens you burn every day, how much are you paying for AI getting lost?

References

Alternative Titles

  1. The most token-wasting part of AI coding has finally been addressed
  2. Stop making Claude/Codex repeatedly scan your repo: This tool shows AI a code map first
  3. When using AI to change code in large repos, the real cost saver is this step
  4. Let AI read 90% less irrelevant code: Why did code-review-graph suddenly become popular?

评论

暂无评论。

登录后可发表评论。

专题：AI Programming
目录