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

> Configure tuicr session polling with review_watch_interval_ms for smooth collaborative editing. Adjust the interval in config.toml for optimal performance. Learn how now.

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

---

**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`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs)

The `Config` struct defines the field as optional:

```rust
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`](https://github.com/agavra/tuicr/blob/main/src/main.rs)

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

```rust
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`](https://github.com/agavra/tuicr/blob/main/src/app/session.rs)

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

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

```bash
$XDG_CONFIG_HOME/tuicr/config.toml

```

Default location when `XDG_CONFIG_HOME` is unset:

```bash
~/.config/tuicr/config.toml

```

Create the directory if needed:

```bash
mkdir -p ~/.config/tuicr

```

### Step 2: Add the `review_watch_interval_ms` Key

Open [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) in your editor and add:

```toml

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

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

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

```toml
review_watch_interval_ms = 250

```

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

### Single-User or Performance-Critical Mode (Disabled)

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

```bash
TUICR_REVIEW_WATCH_INTERVAL_MS=500 tuicr

```

The parser in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) checks environment variables before falling back to [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) values.

## Validating Your Configuration

tuicr logs configuration parsing events. Verify your setting with:

```bash
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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) (parsing), [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs) (application), and [`src/app/session.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/config.toml) require a full restart. The [`main.rs`](https://github.com/agavra/tuicr/blob/main/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.