# How Watch Mode Keeps the Code Review Graph Updated in VS Code

> Learn how watch mode keeps the code review graph updated in VS Code. Discover how file saves and file system watchers maintain a real-time graph for your repository

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

---

**The VS Code extension maintains a real-time code review graph by combining auto-update triggers on file saves with file-system watchers that monitor the SQLite database for incremental changes.**

The `tirth8205/code-review-graph` repository implements a coordinated watch mode that synchronizes your workspace edits with the persisted code review visualization. By layering event listeners with strategic debouncing, the extension ensures the graph remains current without overwhelming system resources. This architecture creates a continuous feedback loop between source code changes and the UI representation.

## Layer 1: Auto-Updating on File Saves

The primary synchronization mechanism reacts to file save operations within the workspace.

### The setupAutoUpdate Listener

In [`code-review-graph-vscode/src/extension.ts`](https://github.com/tirth8205/code-review-graph/blob/main/code-review-graph-vscode/src/extension.ts), the extension registers a `workspace.onDidSaveTextDocument` listener that intercepts every file save event. Before triggering an update, the system validates the `codeReviewGraph.autoUpdate` setting to respect user preferences.

To prevent performance degradation during rapid editing, the implementation employs a **2-second debounce** timer:

```typescript
// Auto-update on file save (extension.ts)
const onSave = vscode.workspace.onDidSaveTextDocument(() => {
  const config = vscode.workspace.getConfiguration("codeReviewGraph");
  if (!config.get<boolean>("autoUpdate", true)) return;

  if (autoUpdateTimer) clearTimeout(autoUpdateTimer);
  autoUpdateTimer = setTimeout(async () => {
    const wsRoot = getWorkspaceRoot();
    if (!wsRoot || !sqliteReader) return;
    await cli.updateGraph(wsRoot);
  }, 2000);
});
context.subscriptions.push(onSave);

```

When the debounce timer expires, the extension invokes `cli.updateGraph()`, which executes the CLI's `update` operation to incrementally modify the `graph.db` file based on the latest source changes.

## Layer 2: Monitoring Database Changes

While Layer 1 pushes updates to the database, Layer 2 ensures the UI immediately reflects those changes by watching the `graph.db` file itself.

### The watchGraphDb FileSystemWatcher

Also defined in [`code-review-graph-vscode/src/extension.ts`](https://github.com/tirth8205/code-review-graph/blob/main/code-review-graph-vscode/src/extension.ts), the `watchGraphDb` function creates a `FileSystemWatcher` targeting `**/.code-review-graph/graph.db`. This watcher handles three distinct file events to maintain UI consistency:

- **onDidChange**: Closes the current `SqliteReader`, reinitializes it with the updated database path, and triggers a tree view refresh via `codeReviewGraph.codeGraph.refresh`
- **onDidCreate**: Instantiates a new `SqliteReader` when the database file appears for the first time
- **onDidDelete**: Disposes the reader and nullifies internal references to prevent memory leaks

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

  watcher.onDidChange(() => {
    if (sqliteReader && dbPathRef.current) {
      sqliteReader.close();
      sqliteReader = new SqliteReader(dbPathRef.current);
      vscode.commands.executeCommand("codeReviewGraph.codeGraph.refresh");
    }
  });

  // Create / Delete handlers omitted for brevity
  context.subscriptions.push(watcher);
}

```

This mechanism creates a reactive pipeline: **source changes** → *auto-update* → **CLI updates `graph.db`** → *file-system watcher* → **Extension reloads UI**.

## Layer 3: CLI-Level Debounced Watching

For command-line watch scenarios, the repository provides a dedicated `GraphWatcher` class that operates independently of the extension UI.

### The GraphWatcher Implementation

Located in [`code-review-graph-vscode/src/backend/watcher.ts`](https://github.com/tirth8205/code-review-graph/blob/main/code-review-graph-vscode/src/backend/watcher.ts), the `GraphWatcher` class wraps VS Code's `FileSystemWatcher` with an additional **500ms debounce** to protect against rapid successive file events:

```typescript
// GraphWatcher – low-level debounced watcher (watcher.ts)
export class GraphWatcher implements vscode.Disposable {
  private readonly watcher: vscode.FileSystemWatcher;
  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 debouncedOnChanged = debounce(onChanged, 500);
    this.disposables.push(
      this.watcher.onDidChange(() => debouncedOnChanged()),
      this.watcher.onDidCreate(() => debouncedOnChanged()),
      this.watcher
    );
  }
  // …dispose implementation…
}

```

This lower-level watcher is primarily consumed by the CLI's `watch` command, providing efficient file monitoring for headless or terminal-based workflows.

## Summary

- **Auto-update on save**: The `workspace.onDidSaveTextDocument` listener in [`src/extension.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/extension.ts) triggers debounced CLI updates (2000ms) to balance responsiveness with system performance.
- **Database change detection**: A dedicated `FileSystemWatcher` monitors `graph.db` modifications, automatically reloading the `SqliteReader` and refreshing the tree view when the underlying data changes.
- **Configurable debouncing**: The extension uses a 2-second debounce for save operations, while the CLI `GraphWatcher` applies a 500ms debounce for direct file-system monitoring.
- **Resource cleanup**: Both the extension and CLI watchers properly dispose of `SqliteReader` instances and file handles when databases are deleted or the extension deactivates.

## Frequently Asked Questions

### How do I disable auto-update in watch mode?

Set the `codeReviewGraph.autoUpdate` configuration to `false` in your VS Code settings. When disabled, the `workspace.onDidSaveTextDocument` listener returns early without scheduling the debounced update call, requiring manual graph refreshes via the command palette instead.

### Why is there a delay after saving files before the graph updates?

The extension implements a **2-second debounce** in the `setupAutoUpdate` function to prevent redundant CLI executions during rapid editing. This timer resets with each subsequent save, ensuring the graph only updates once you have paused typing for two seconds.

### What happens to the UI if the graph.db file is deleted?

The `watchGraphDb` function includes an `onDidDelete` handler that disposes the current `SqliteReader` instance and clears internal references. This prevents memory leaks and allows the extension to gracefully handle the missing database until it is regenerated by the next update cycle.

### Where is the debounce logic implemented for CLI watching?

The CLI uses the `GraphWatcher` class defined in [`src/backend/watcher.ts`](https://github.com/tirth8205/code-review-graph/blob/main/src/backend/watcher.ts), which wraps VS Code's `FileSystemWatcher` with a 500-millisecond debounce. This protects against rapid successive file events that could otherwise trigger redundant graph processing operations in terminal-based workflows.