How to Configure the Daemon watch.toml for Multiple Repositories in code-review-graph

To configure the daemon watch.toml for multiple repositories, create or edit ~/.code-review-graph/watch.toml and define separate [[repos]] tables for each codebase, specifying the absolute path and an optional alias, while the ConfigWatcher automatically reloads changes without restarting the service.

The code-review-graph daemon monitors local repositories for code review graph generation through a centralized TOML configuration file. To configure the daemon watch.toml for multiple repositories, you populate this file with repository entries and global settings that control polling behavior and logging, all parsed by the load_config() function in code_review_graph/daemon.py.

Location and Structure of watch.toml

The daemon reads its configuration from ~/.code-review-graph/watch.toml (line 41 in code_review_graph/daemon.py). This file uses TOML format with top-level keys for global daemon settings and array-of-tables syntax for repository definitions.

Required Repository Fields

Each repository entry is a TOML table of the form [[repos]] containing specific fields validated at startup:

• path: Absolute or tilde-expanded path to the repository root. The daemon validates that the directory exists and contains a VCS marker (.git, .svn, or .code-review-graph folder) before accepting it (lines 27‑38).
• alias: Human-readable identifier for the repository. If omitted, the daemon falls back to the directory name using repo_path.name (lines 45‑46).

Optional Global Settings

The daemon supports three optional top-level configuration keys with sensible defaults (lines 66‑73):

• session_name: Logical name used in log messages (defaults to "crg-watch").
• log_dir: Directory where per-repository log files are written (defaults to "~/.code-review-graph/logs").
• poll_interval: Seconds between file-system polls when the watchdog library is unavailable.

Example Configuration for Multiple Repositories

To monitor multiple codebases simultaneously, append additional [[repos]] tables to the same file:

# ~/.code-review-graph/watch.toml

session_name = "crg-watch"
log_dir = "~/.code-review-graph/logs"
poll_interval = 2

[[repos]]
path = "/home/alice/project-alpha"
alias = "alpha"

[[repos]]
path = "/home/alice/project-beta"
alias = "beta"

[[repos]]
path = "/home/alice/project-gamma"

# alias omitted → defaults to "project-gamma"

When the daemon starts, load_config() (lines 84‑92) parses this configuration and spawns a separate code-review-graph watch child process for each repository entry. The daemon persists child PIDs to ~/.code-review-graph/daemon-state.json for cross-process status queries (lines 56‑58).

Validating Repository Paths

Before spawning watchers, the daemon validates each repository path according to the logic in code_review_graph/daemon.py. The directory must exist and contain a version control marker. Accepted markers include .git directories, .svn folders, or a .code-review-graph folder indicating a valid repository root (lines 27‑38).

Managing Repositories via CLI

Instead of manual editing, use the crg-daemon CLI to modify the configuration programmatically.

Adding a repository:

crg-daemon add /home/alice/project-delta --alias delta

Removing a repository:

crg-daemon remove beta

Inspecting current configuration:

crg-daemon status

These commands update watch.toml safely while the daemon is running.

Dynamic Configuration Reloading

The daemon implements a ConfigWatcher that monitors watch.toml for modifications (lines 77‑88). When you add, remove, or update repository entries, the daemon reconciles these changes automatically—starting new watchers for added repositories and terminating processes for removed ones—without requiring a service restart.

Summary

• File location: Configure repositories in ~/.code-review-graph/watch.toml as read by the daemon at line 41 in code_review_graph/daemon.py.
• Entry format: Use [[repos]] tables with required path and optional alias fields.
• Path validation: Repositories must contain .git, .svn, or .code-review-graph markers before the daemon accepts them (lines 27‑38).
• Global options: Set session_name, log_dir, and poll_interval at the top level to control daemon behavior (lines 66‑73).
• Hot reloading: The ConfigWatcher detects file changes and updates running watchers dynamically, eliminating the need for restarts (lines 77‑88).

Frequently Asked Questions

Where is the watch.toml file located?

The daemon expects the configuration file at ~/.code-review-graph/watch.toml according to line 41 in code_review_graph/daemon.py. This path is hardcoded as the default location for the daemon's global settings and repository list, and the daemon creates the parent directory if it does not exist.

What happens if I omit the alias field?

If the alias field is missing from a [[repos]] entry, the daemon extracts the final directory component from the path using repo_path.name and uses that string as the identifier (lines 45‑46). This ensures every monitored repository has a human-readable reference even without explicit configuration.

Can I add repositories without editing the file manually?

Yes. The crg-daemon CLI provides add and remove subcommands that safely modify watch.toml programmatically. For example, running crg-daemon add /path/to/repo --alias myproject appends the repository to the configuration and triggers the daemon's file watcher to spawn a new monitoring process immediately.

How does the daemon handle configuration changes?

The ConfigWatcher class monitors watch.toml for filesystem events (lines 77‑88). When the file changes, the daemon reloads the configuration via load_config() and reconciles the active child processes—starting new watchers for added repositories and stopping those for removed entries—without requiring a service restart.

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