# How to Use review_watch_interval_ms for Collaborative Editing in tuicr

> Learn how to use review_watch_interval_ms to enable automatic merging of external edits into your tuicr TUI session for seamless collaborative editing.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-07

---

**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`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs)** (line ≈ 134): `pub review_watch_interval_ms: Option<usize>`
- **[`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/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:

```toml

# ~/.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**:

```toml
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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/main.rs)** (lines ≈ 313‑314) applies the parsed configuration to the running application instance:

```rust
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`](https://github.com/agavra/tuicr/blob/main/src/app/session.rs)** file (line ≈ 14) contains the `set_review_watch_interval_ms` method that stores the interval and initializes the background poller:

```rust
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:

```toml
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:

```toml
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:

```bash
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`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) (lines ≈ 1154‑1160).
- The setting propagates through [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs) (lines ≈ 313‑314) to [`src/app/session.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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.