Incremental Updates & File Watching

Relevant source files

The following files were used as context for generating this wiki page:

• code_review_graph/incremental.py
• code_review_graph/main.py
• code_review_graph/cli.py
• code_review_graph/skills.py
• code-review-graph-vscode/src/extension.ts
• CLAUDE.md

Introduction

The Incremental Updates & File Watching system is a core component of code-review-graph designed to maintain a persistent, structurally accurate knowledge graph while minimizing computational overhead and token usage. Instead of re-parsing an entire codebase for every change, the system utilizes Git-based change detection and real-time filesystem monitoring to identify and re-index only the modified files and their immediate dependencies.

This local-first approach ensures that the SQLite-backed graph remains synchronized with the current state of the source code. The system integrates across multiple platforms—including CLI, VS Code, and various MCP-compatible AI coding tools—to provide seamless, nearly instantaneous updates that typically complete in under 2 seconds for large projects.

Sources: CLAUDE.md:1-15, README.zh-CN.md:工作原理

Incremental Update Mechanism

Incremental updates are driven primarily by Git-based change detection. The system compares the current state of the repository against a base reference (defaulting to HEAD~1) to determine the specific files that have been added, modified, or deleted.

Logic and Data Flow

When an incremental update is triggered, the system follows a structured pipeline:

1. Change Detection: It queries Git to identify changed files.
2. Dependency Mapping: It identifies dependencies and affected nodes within the graph using SHA-256 hashing to verify if content has truly changed.
3. Targeted Re-parsing: Only the changed files are re-processed using Tree-sitter parsers.
4. Graph Synthesis: The SQLite database is updated with new nodes and edges while stale data is pruned.

The diagram above illustrates the incremental update flow from change detection to graph finalization.
Sources: code_review_graph/cli.py:596-620, code_review_graph/main.py:100-115, README.zh-CN.md:增量更新流程

Key Components

Component	Description	Source
build_or_update_graph	Core function orchestrating both full builds and incremental updates.	code_review_graph/main.py:100-115
get_changed_files	Utilizes Git commands to list files modified since a specific base ref.	code_review_graph/cli.py:650-655
GraphStore	Manages the SQLite database, handling node/edge upserts and metadata.	CLAUDE.md:Architecture
SHA-256 Hashing	Used to verify if file content matches stored data to skip redundant parsing.	README.zh-CN.md:增量更新

File Watching & Daemon Mode

To ensure the graph is always up-to-date without manual intervention, the system provides a file-watching service. This can run as a background daemon or as a thread within an active MCP server session.

Filesystem Monitoring

The watch command initializes a watcher that monitors the repository root for filesystem events. Upon detecting a file save or modification, it triggers a background incremental update.

• MCP Server Integration: The MCP server can be started with the --auto-watch flag, which spawns a background thread to monitor changes while the server communicates with AI tools.
• VS Code Integration: The VS Code extension includes a FileSystemWatcher specifically for the graph.db file to refresh tree views, as well as a debounced onDidSaveTextDocument listener to trigger updates.

This sequence shows how a file save leads to a background graph update and subsequent UI refresh.
Sources: code-review-graph-vscode/src/extension.ts:474-530, code_review_graph/main.py:560-575, code_review_graph/cli.py:730-740

Multi-Repo Daemon

The CLI provides a daemon command set to manage a background service that can monitor multiple registered repositories simultaneously.

Command	Action
daemon start	Starts the background watch service.
daemon add <path>	Registers a new repository for the daemon to watch.
daemon status	Displays the health of the daemon and active watchers.
daemon stop	Termintes the background processes.

Sources: code_review_graph/cli.py:51-65, code_review_graph/cli.py:535-555

Platform Hooks & Automation

Incremental updates are also automated through platform-specific hooks and Git integration.

Git Pre-commit Hooks

The system can install a Git pre-commit hook. This hook automatically runs code-review-graph update and code-review-graph detect-changes --brief before a commit is finalized, ensuring the developer sees a risk summary of their changes immediately.

AI Tool Integration

AI coding platforms like Codex, Claude, and Gemini use custom settings to trigger updates:

• Codex: Uses PostToolUse hooks in hooks.json to trigger updates after Write or Edit tools are used.
• Gemini CLI: Uses AfterTool hooks in .gemini/settings.json to run updates after write_file or replace operations.
• VS Code: Automatically triggers a debounced update (2000ms delay) on every document save if autoUpdate is enabled in settings.

Sources: code_review_graph/skills.py:440-470, code_review_graph/skills.py:740-770, code-review-graph-vscode/src/extension.ts:515-525

Conclusion

The incremental update and file-watching infrastructure is fundamental to the "local-first" philosophy of code-review-graph. By combining Git-based diffing with real-time filesystem watchers and platform-native hooks, the system maintains a high-performance knowledge graph that enables token-efficient code reviews. This proactive synchronization ensures that AI assistants always operate on the most recent architectural context without the latency of a full project re-index.