How to Use review_watch_interval_ms for Collaborative Editing in tuicr

The review_watch_interval_ms configuration option sets the millisecond interval for polling persisted review sessions, enabling tuicr to automatically merge external edits from other processes into your active TUI session.

The tuicr terminal user interface for code review supports real-time collaborative workflows by synchronizing session state between the TUI and external CLI processes. Configuring review_watch_interval_ms controls how frequently the application checks for changes made by other instances, ensuring your review session stays current without requiring manual reloads.

What review_watch_interval_ms Controls

In tuicr, the review_watch_interval_ms parameter defines the duration between background polls of the persisted review store. When set to a positive integer, the application spawns a lightweight timer that checks the session files (typically located in ~/.local/share/tuicr/reviews/) for modifications. If external changes are detected—such as comments added via the tuicr review CLI—the timer triggers a merge of those edits into your in-memory session.

The configuration is defined as an optional unsigned integer in the source:

• src/config/mod.rs (line ≈ 134): pub review_watch_interval_ms: Option<usize>
• src/config/mod.rs (lines ≈ 1125‑1166): Contains validation tests ensuring negative values are rejected with warnings

Configuring the Polling Interval

Configuration File Location

Tuicr loads settings from a TOML file at $XDG_CONFIG_HOME/tuicr/config.toml (defaulting to ~/.config/tuicr/config.toml). Create this file if it does not exist.

Basic Syntax

Add the key to your configuration file to set the interval in milliseconds:

# ~/.config/tuicr/config.toml

review_watch_interval_ms = 250

A value of 250 milliseconds provides near real-time synchronization suitable for most collaborative editing scenarios.

Disabling Polling

To completely disable automatic synchronization and prevent background polling activity, set the value to 0:

review_watch_interval_ms = 0

When disabled, external changes will only appear when you manually reload the session.

Handling Invalid Values

The parser ignores negative values and emits a warning. According to the test suite in src/config/mod.rs (lines ≈ 1154‑1160), supplying a negative number results in the configuration falling back to default behavior while logging the invalid input.

Implementation Details from the Source Code

Configuration Parsing

The Config struct in src/config/mod.rs handles the optional field definition at line ≈ 134 and the TOML deserialization logic around line ≈ 427. This structure supports both file-based configuration and environment variable overrides.

Application Initialization

During startup, src/main.rs (lines ≈ 313‑314) applies the parsed configuration to the running application instance:

if let Some(interval_ms) = cfg.review_watch_interval_ms {
    app.set_review_watch_interval_ms(interval_ms as u64);
}

This code converts the configured milliseconds into a u64 and passes it to the session manager.

Session Polling Logic

The src/app/session.rs file (line ≈ 14) contains the set_review_watch_interval_ms method that stores the interval and initializes the background poller:

pub fn set_review_watch_interval_ms(&mut self, interval_ms: u64) {
    // Stores the interval for the background timer that synchronizes sessions
}

This method drives the timer responsible for detecting and merging external session changes.

Practical Configuration Examples

Example 1: High-Frequency Collaboration

For fast networks or when multiple reviewers are actively editing simultaneously, reduce the interval to 100 ms:

review_watch_interval_ms = 100

Example 2: Laptop Power Saving

To reduce background activity and save battery when collaboration is not needed, increase the interval to 2000 ms (2 seconds) or disable it entirely:

review_watch_interval_ms = 2000

Example 3: Environment Variable Override

You can temporarily override the configuration file setting using an environment variable before launching tuicr:

TUICR_REVIEW_WATCH_INTERVAL_MS=500 tuicr

This approach is useful for testing different polling frequencies without modifying persistent configuration files.

Summary

• review_watch_interval_ms controls the millisecond frequency for polling persisted review sessions in tuicr.
• Set the value in ~/.config/tuicr/config.toml under the review_watch_interval_ms key.
• A value of 0 disables polling entirely, while positive values enable automatic merging of external edits.
• Negative values are rejected with a warning according to validation tests in src/config/mod.rs (lines ≈ 1154‑1160).
• The setting propagates through src/main.rs (lines ≈ 313‑314) to src/app/session.rs (line ≈ 14) to drive the background synchronization timer.

Frequently Asked Questions

What is the default value for review_watch_interval_ms in tuicr?

The default value is 250 milliseconds when the configuration key is omitted. This provides a balance between responsiveness and system resource usage for most collaborative editing scenarios.

Can I disable collaborative editing synchronization completely?

Yes. Set review_watch_interval_ms = 0 in your configuration file. This disables the background poller, preventing automatic merging of external session changes. You will need to manually reload the session to see updates from other processes.

Why does tuicr ignore negative values for review_watch_interval_ms?

The configuration parser treats negative values as invalid input. According to the test suite in src/config/mod.rs (lines ≈ 1154‑1160), negative numbers trigger a warning and the application falls back to default behavior, as polling intervals cannot be negative durations.

Where does tuicr look for the review sessions it polls?

Tuicr polls the review store directory, typically located at ~/.local/share/tuicr/reviews/. The review_watch_interval_ms setting controls how often the application checks these persisted JSON files for modifications made by other CLI or TUI instances.

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