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

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, 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. This module implements a supervisor pattern that reads 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 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, 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 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. 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 and starts watching it immediately.
• remove <path_or_alias> – Removes a repository from 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:

# 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, managed via the add and remove commands.
• The supervisor in daemon_cli.py spawns per-repo watchers and auto-restarts failed processes.
• File-system monitoring uses the watchdog library within daemon_watcher.py subprocesses.
• Changes trigger 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}