# How crg-daemon Watches and Auto-Updates Graphs in code-review-graph

> Discover how crg-daemon automatically updates code-review-graph graphs by watching file system changes and leveraging supervisor for efficient repo monitoring and restarts.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: internals
- Published: 2026-07-26

---

**The crg-daemon background service monitors configured repositories via file-system watchers and automatically rebuilds the code-review graph whenever source files change, using a supervisor process that manages per-repo child processes with health checks and auto-restart capabilities.**

The `code-review-graph` project provides a multi-repository daemon that eliminates the need for manual graph rebuilds after every code change. By running `crg-daemon` as a persistent background service, developers can ensure their code review knowledge graphs remain current without intervention according to the source code in `tirth8205/code-review-graph`.

## Configuration with watch.toml

The daemon persists its repository registry in a TOML configuration file named [`watch.toml`](https://github.com/tirth8205/code-review-graph/blob/main/watch.toml), located in the daemon’s data directory. When you execute `crg-daemon add <path> [--alias NAME]`, the CLI appends an entry to this file, mapping the repository path to an optional alias for later reference.

## Daemon Architecture and Entry Point

The main entry point for the daemon is **[`code_review_graph/daemon_cli.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/daemon_cli.py)**. This module implements a supervisor pattern that reads [`watch.toml`](https://github.com/tirth8205/code-review-graph/blob/main/watch.toml) and manages the lifecycle of per-repository watcher processes.

### The Supervisor Process

When you run `crg-daemon start`, the supervisor initializes a health-check loop that monitors all registered repositories. It spawns a dedicated child process for each entry in [`watch.toml`](https://github.com/tirth8205/code-review-graph/blob/main/watch.toml) and periodically verifies that each watcher is still alive. If a subprocess crashes or exits unexpectedly, the supervisor automatically restarts it to guarantee continuous monitoring.

### Per-Repository File Watching

Each repository is monitored by a dedicated watcher subprocess, implemented in **[`code_review_graph/daemon_watcher.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/daemon_watcher.py)**, which utilizes the **watchdog** library to observe file-system events. These watchers monitor the source tree for adds, deletes, moves, and edits. When a change is detected, the watcher triggers an update sequence rather than rebuilding the entire graph from scratch.

## Auto-Update Pipeline

Upon detecting a file change, the watcher invokes **[`code_review_graph/update_graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/update_graph.py)** to parse the modified files and incrementally update the internal knowledge graph. This pipeline writes the refreshed graph back to the on-disk cache immediately, ensuring that the code-review graph reflects the latest repository state without requiring a manual rebuild.

## CLI Management Commands

The daemon exposes a thin command-line interface documented in **[`docs/COMMANDS.md`](https://github.com/tirth8205/code-review-graph/blob/main/docs/COMMANDS.md)**. The available sub-commands include:

- **`start [--foreground]`** – Launches the supervisor process. Without the flag, it runs as a background daemon.
- **`stop`** – Terminates the supervisor and all active watcher subprocesses.
- **`restart [--foreground]`** – Stops and then restarts the daemon.
- **`status`** – Displays which repositories are being watched and reports the liveness of each watcher process.
- **`logs [--repo ALIAS] [--follow] [--lines N]`** – Tails the log file for the daemon or a specific repository.
- **`add <path> [--alias NAME]`** – Registers a new repository in [`watch.toml`](https://github.com/tirth8205/code-review-graph/blob/main/watch.toml) and starts watching it immediately.
- **`remove <path_or_alias>`** – Removes a repository from [`watch.toml`](https://github.com/tirth8205/code-review-graph/blob/main/watch.toml) and stops its watcher.

## Logging and Health Monitoring

The supervisor maintains a separate log file for each repository to isolate debugging output. The health-check loop ensures high availability by restarting any dead watchers automatically. You can inspect real-time activity using the `crg-daemon logs` command with the `--follow` flag.

### Practical Usage Example

Register repositories and start the daemon with the following commands:

```bash

# Register two repositories for automatic watching

crg-daemon add ~/projects/api       --alias api
crg-daemon add ~/projects/webapp   # alias defaults to folder name

# Start the daemon (runs in background)

crg-daemon start

# Check which repos are being watched and that each watcher is alive

crg-daemon status

# Tail the log of the "api" repo in real-time

crg-daemon logs --repo api -f

# Stop everything when you no longer need automatic updates

crg-daemon stop

```

## Summary

- **`crg-daemon`** is the background service that keeps code-review-graph synchronized automatically.
- Configuration is stored in **[`watch.toml`](https://github.com/tirth8205/code-review-graph/blob/main/watch.toml)**, managed via the `add` and `remove` commands.
- The supervisor in **[`daemon_cli.py`](https://github.com/tirth8205/code-review-graph/blob/main/daemon_cli.py)** spawns per-repo watchers and auto-restarts failed processes.
- File-system monitoring uses the **watchdog** library within **[`daemon_watcher.py`](https://github.com/tirth8205/code-review-graph/blob/main/daemon_watcher.py)** subprocesses.
- Changes trigger **[`update_graph.py`](https://github.com/tirth8205/code-review-graph/blob/main/update_graph.py)** to refresh the graph incrementally.
- The CLI provides `start`, `stop`, `status`, and `logs` commands for operational control.

## Frequently Asked Questions

### What is crg-daemon in code-review-graph?

**`crg-daemon`** is the multi-repository background service included in the code-review-graph project. It continuously monitors registered repositories for file changes and automatically updates the knowledge graph without manual intervention.

### How does crg-daemon detect file changes?

The daemon spawns per-repository watcher subprocesses that use the **watchdog** library to monitor file-system events. When a file is added, deleted, or modified, the watcher detects the event and triggers the graph update pipeline.

### Where does crg-daemon store its configuration?

The daemon writes its repository registry to a TOML file named **[`watch.toml`](https://github.com/tirth8205/code-review-graph/blob/main/watch.toml)** in its data directory. This file is updated automatically when you run `crg-daemon add` or `crg-daemon remove`.

### How can I debug a specific repository watcher?

Use the **`crg-daemon logs`** command with the `--repo` flag to isolate output for a specific repository. For real-time debugging, append the `--follow` (or `-f`) flag to tail the log as the watcher detects changes and updates the graph.