# How Watch Mode in code-review-graph Detects File Changes and Triggers Incremental Updates

> Discover how watch mode in code-review-graph detects file changes using a 3-layer architecture and triggers incremental graph updates automatically. Boost your workflow.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-07-23

---

**Watch mode in the code-review-graph VS Code extension uses a three-layer architecture combining command-based CLI entry points, VS Code FileSystemWatcher instances, and debounced callbacks to automatically detect SQLite database changes and refresh the graph view without manual intervention.**

The repository **tirth8205/code-review-graph** implements an intelligent file monitoring system that keeps the code review graph synchronized with your evolving codebase. When enabled, watch mode tracks modifications to the underlying SQLite database and triggers incremental updates to the UI components.

## Architecture Overview: The Three-Layer Detection System

The watch mode implementation spans three tightly coupled layers that work together to provide seamless real-time updates. According to the source code in [`src/extension.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/extension.ts) and [`src/backend/watcher.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/backend/watcher.ts), the system combines CLI command registration, file system event listeners, and debounced change detection to manage the graph database lifecycle.

The architecture ensures that developers only need to enable watch mode once, after which any changes to source files that affect the graph are automatically reflected in the VS Code UI.

## Layer 1: Command Registration and CLI Entry Point

The watch mode journey begins in [`src/extension.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/extension.ts) at lines 547-560, where the extension registers the `codeReviewGraph.watchGraph` command. When a user selects **"Code Review Graph: Watch Graph"** from the command palette, the extension invokes `CliWrapper.watchGraph(workspaceRoot)` to initialize the monitoring daemon.

This entry point serves as the bridge between user interaction and the backend file monitoring system, forwarding the workspace root path to the underlying watcher implementation.

## Layer 2: Real-Time File System Monitoring

The `watchGraphDb` function (lines 94-136 in [`src/extension.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/extension.ts)) creates a **VS Code FileSystemWatcher** that listens for **create**, **change**, and **delete** events on the pattern `**/.code-review-graph/graph.db`. This watcher monitors the generated SQLite database file that stores the code review graph data.

When the underlying analysis tool rebuilds the graph, it rewrites this database file, triggering the watcher events. The handler implementation manages the `SqliteReader` lifecycle by closing the existing connection and opening a fresh one pointing to the updated file.

```typescript
function watchGraphDb(context: vscode.ExtensionContext): void {
  const watcher = vscode.workspace.createFileSystemWatcher(
    "**/.code-review-graph/graph.db"
  );

  // Re-open the DB on change
  watcher.onDidChange(() => {
    if (sqliteReader && dbPathRef.current) {
      sqliteReader.close();
      sqliteReader = new SqliteReader(dbPathRef.current);
      vscode.commands.executeCommand("codeReviewGraph.codeGraph.refresh");
    }
  });

  // Initialize on first creation
  watcher.onDidCreate(async () => {
    const wsRoot = getWorkspaceRoot();
    if (wsRoot && !sqliteReader) {
      const dbPath = findGraphDb(wsRoot);
      if (dbPath) {
        dbPathRef.current = dbPath;
        sqliteReader = new SqliteReader(dbPath);
        vscode.commands.executeCommand("codeReviewGraph.codeGraph.refresh");
      }
    }
  });

  // Clean up on delete
  watcher.onDidDelete(() => {
    sqliteReader?.close();
    sqliteReader = undefined;
    dbPathRef.current = "";
  });

  context.subscriptions.push(watcher);
}

```

## Layer 3: Debounced Change Detection

The `GraphWatcher` class in [`src/backend/watcher.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/backend/watcher.ts) (lines 25-60) provides a specialized implementation that wraps a `FileSystemWatcher` around the `graph.db` file itself. This class implements a **500ms debounce** on the `onChanged` callback to prevent rapid successive updates when the graph database is being rebuilt.

Using `vscode.RelativePattern`, the watcher monitors the specific database file path and ensures that burst write operations only trigger a single refresh cycle. The class also implements the `vscode.Disposable` interface for proper resource cleanup.

```typescript
export class GraphWatcher implements vscode.Disposable {
  constructor(dbPath: string, onChanged: () => void) {
    const dir = path.dirname(dbPath);
    const filename = path.basename(dbPath);
    this.watcher = vscode.workspace.createFileSystemWatcher(
      new vscode.RelativePattern(vscode.Uri.file(dir), filename)
    );
    const debounced = debounce(onChanged, 500);
    this.disposables.push(
      this.watcher.onDidChange(() => debounced()),
      this.watcher.onDidCreate(() => debounced()),
      this.watcher
    );
  }
  dispose() { /* cleanup implementation */ }
}

```

## Database Lifecycle and UI Synchronization

When a file change event fires, the system executes a precise sequence to maintain data integrity and UI consistency. First, the current `SqliteReader` instance closes its connection to prevent file locks. Then, a new reader opens a connection to the updated database file.

Immediately after the database refresh, the extension executes the `codeReviewGraph.codeGraph.refresh` command to rebuild the tree view. This triggers updates across optional UI components including the graph webview, SCM decorations, and the output channel, ensuring the entire interface reflects the newest graph state.

## Summary

- **Watch mode in code-review-graph** operates through a three-layer architecture combining CLI commands, file system watchers, and debounced detection.
- The `watchGraphDb` function in [`src/extension.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/extension.ts) creates a **FileSystemWatcher** monitoring `**/.code-review-graph/graph.db` for create, change, and delete events.
- The **GraphWatcher** class in [`src/backend/watcher.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/backend/watcher.ts) implements a **500ms debounce** to optimize performance during rapid database rebuilds.
- Database connections cycle through close-and-reopen operations to prevent file locks while ensuring data freshness.
- UI updates propagate automatically via the `codeReviewGraph.codeGraph.refresh` command, synchronizing the tree view, SCM decorations, and webview components.

## Frequently Asked Questions

### What file pattern does watch mode monitor?

Watch mode monitors the SQLite database file at `**/.code-review-graph/graph.db` rather than individual source files. This pattern ensures the extension detects changes only after the underlying analysis tool has completed graph reconstruction, preventing partial or inconsistent updates.

### How does watch mode prevent excessive updates during rapid file changes?

The **GraphWatcher** class implements a **500-millisecond debounce** on change callbacks. When the database file undergoes rapid successive writes during graph rebuilding, the debounce mechanism consolidates multiple events into a single refresh cycle, optimizing performance and preventing UI flicker.

### What happens when the graph.db file is deleted while watch mode is active?

The `watchGraphDb` function includes an `onDidDelete` event handler that closes the current `SqliteReader` connection and clears the database path reference. This prevents errors from stale file handles and allows the system to reinitialize cleanly when the file is recreated.

### Can watch mode detect changes in multiple workspace folders simultaneously?

Yes, the architecture supports multi-root workspaces. The `CliWrapper.watchGraph` method accepts the `workspaceRoot` parameter, and the file watcher pattern `**/.code-review-graph/graph.db` matches database files across all workspace folders, triggering independent refresh cycles for each detected change.