How to Configure Session Polling with `review_watch_interval_ms` for Collaborative Editing in tuicr

Set the review_watch_interval_ms config key in ~/.config/tuicr/config.toml to control how often tuicr polls for external session changes—use 250 for quarter-second polling, 0 to disable, and restart the application to apply.

The review_watch_interval_ms configuration option enables collaborative editing in tuicr by periodically checking the persisted review session files for external modifications. This allows multiple processes (or users) to work on the same code review simultaneously, with changes automatically merging into the active TUI session. According to the tuicr source code, this setting bridges the configuration layer, application runtime, and session polling mechanism.

What review_watch_interval_ms Controls

When enabled, tuicr spawns a background timer that monitors the review store directory (~/.local/share/tuicr/reviews/) for changes to the current session's JSON file. The interval value determines polling frequency:

Value	Behavior
Positive integer	Poll every N milliseconds and merge external edits
0	Disable polling entirely; manual reload required
Negative values	Ignored with a warning logged to stderr

The feature supports scenarios where review comments are added via the tuicr review CLI while a TUI session remains open, keeping both interfaces synchronized without restart.

Where the Setting Lives in the Source Code

Understanding the implementation helps diagnose configuration issues and customize behavior.

Configuration Definition: src/config/mod.rs

The Config struct defines the field as optional:

pub review_watch_interval_ms: Option<usize>,

Line 134 declares the type, while line 427 contains the TOML parsing logic that extracts the value from the configuration file.

Runtime Application: src/main.rs

After loading configuration, the main entry point applies the interval:

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

Lines 313–314 demonstrate the bridge from parsed config to active application state.

Session Polling: src/app/session.rs

The method storing the interval for background operations appears at line 14:

pub fn set_review_watch_interval_ms(&mut self, interval_ms: u64) { ... }

This method initializes the timer that drives the collaborative merge behavior.

How to Configure Session Polling

Follow these steps to enable and tune collaborative editing in your environment.

Step 1: Locate or Create the Config File

tuicr follows the XDG Base Directory specification. The configuration file path is:

$XDG_CONFIG_HOME/tuicr/config.toml

Default location when XDG_CONFIG_HOME is unset:

~/.config/tuicr/config.toml

Create the directory if needed:

mkdir -p ~/.config/tuicr

Step 2: Add the review_watch_interval_ms Key

Open config.toml in your editor and add:

# ~/.config/tuicr/config.toml

review_watch_interval_ms = 250

This sets a 250-millisecond polling interval, matching tuicr's built-in default.

Step 3: Restart tuicr

Configuration is read at startup. Exit any running tuicr instance and relaunch:

tuicr

Alternatively, reload the current session with :e if already inside the TUI.

Configuration Examples for Common Scenarios

Near Real-Time Collaboration (100 ms)

For low-latency environments where multiple editors work simultaneously:

review_watch_interval_ms = 100

The increased polling frequency reduces merge latency at the cost of marginally higher CPU usage.

Standard Collaborative Workflow (250 ms)

review_watch_interval_ms = 250

Balanced responsiveness and resource usage. Suitable for most team review sessions.

Single-User or Performance-Critical Mode (Disabled)

review_watch_interval_ms = 0

Eliminates background polling entirely. Use when:

• Only one process accesses reviews
• Minimizing system load is prioritized
• Manual session reload :e is acceptable

Environment Variable Override

Inject configuration without modifying files:

TUICR_REVIEW_WATCH_INTERVAL_MS=500 tuicr

The parser in src/config/mod.rs checks environment variables before falling back to config.toml values.

Validating Your Configuration

tuicr logs configuration parsing events. Verify your setting with:

tuicr --debug 2>&1 | grep -i "watch_interval"

Expected output confirms the applied millisecond value. If negative values are provided, the warning appears referencing lines 1154–1160 of the test suite in src/config/mod.rs.

Summary

• review_watch_interval_ms in ~/.config/tuicr/config.toml controls collaborative editing polling frequency
• Three files implement the feature: src/config/mod.rs (parsing), src/main.rs (application), and src/app/session.rs (polling)
• Recommended values: 250 for default collaboration, 100 for faster sync, 0 to disable
• Restart required after configuration changes; environment variables provide temporary overrides

Frequently Asked Questions

What happens if I set review_watch_interval_ms to a very low value?

Values below 50 milliseconds may cause excessive disk I/O and CPU usage without meaningful latency improvements. The filesystem and tuicr's JSON deserialization become bottlenecks before the polling interval does. The source code in src/app/session.rs uses a simple timer without debouncing, so extremely low values execute exactly as specified.

Can multiple tuicr instances safely edit the same review session?

Yes, provided all instances have polling enabled with positive review_watch_interval_ms values. Each instance detects the other's changes via file modification timestamps and merges non-conflicting edits. Conflicting edits on the same comment trigger last-write-wins behavior based on filesystem ordering.

Where are review sessions stored for the poller to find?

The poller monitors ~/.local/share/tuicr/reviews/ (or $XDG_DATA_HOME/tuicr/reviews/). Each session is a JSON file named {session_id}.json. External processes like tuicr review write to this directory, and the polling mechanism detects those writes.

Why does my configuration change not take effect?

tuicr reads configuration once at startup. Changes to config.toml require a full restart. The main.rs logic at lines 313–314 executes during initialization, not during session reload. Use :e to refresh file content within a session, but full config reloading requires restart.

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