How `OFFICECLI_RESIDENT_FLUSH` Controls Document Persistence in OfficeCLI

The OFFICECLI_RESIDENT_FLUSH environment variable determines when OfficeCLI writes the in-memory document back to disk, offering four modes that trade durability against performance.

The OFFICECLI_RESIDENT_FLUSH environment variable is the primary control mechanism for the resident server's persistence behavior in iOfficeAI/OfficeCLI. When running commands against .docx, .xlsx, or .pptx files, OfficeCLI maintains a live in-memory copy (the "resident") to enable rapid successive modifications. This variable dictates exactly when that memory buffer synchronizes to the filesystem, ranging from immediate per-command flushes to adaptive background saves or manual-only persistence.

Understanding the Resident Flush Mechanism

The resident server keeps documents hot in memory to eliminate redundant disk I/O between commands. However, external programs—such as Python-docx, OpenPyXL, or Microsoft Word—only see changes once the resident flushes its DOM to disk. The OFFICECLI_RESIDENT_FLUSH variable configures this synchronization timing by selecting one of four distinct policies defined in src/officecli/Core/ResidentFlushPolicy.cs (lines 5–15).

The Four OFFICECLI_RESIDENT_FLUSH Modes

During static initialization of ResidentServer (lines 123–127 in src/officecli/ResidentServer.cs), the variable is parsed and stored in the static fields FlushMode and FixedFlushInterval (lines 128–142). The supported values are:

each – Deterministic Durability

Setting OFFICECLI_RESIDENT_FLUSH=each forces a flush before every mutation command returns. This guarantees that the file on disk always reflects the latest change, ensuring external tools see immediate updates. The trade-off is an extra O(n) serialization cost per command.

auto – Adaptive Background Save (Default)

When unset or set to auto, the system uses an adaptive interval calculated as clamp(4 × EMA(save-time), 2s, 10s). This exponential moving average (updated via RecordSaveDuration at lines 57–68 in ResidentServer.cs) ensures background saves never consume more than approximately 25% of wall-clock time while keeping idle latency between 2 and 10 seconds.

<N> – Fixed Idle Interval

Specify a positive integer (e.g., OFFICECLI_RESIDENT_FLUSH=5) to flush after exactly N seconds of resident idle time. This reproduces pre-adaptive behavior and offers predictable timing without the variability of the EMA calculation.

off or 0 – Manual Control

Setting OFFICECLI_RESIDENT_FLUSH=off disables automatic flushing entirely. Changes persist only in memory until you explicitly invoke officecli save, officecli close, or terminate the process.

Legacy Compatibility and Variable Parsing

If OFFICECLI_RESIDENT_FLUSH is undefined, OfficeCLI checks the legacy alias OFFICECLI_RESIDENT_IDLE_SAVE_SECONDS for backward compatibility (same initialization block, lines 123–127). The ResidentFlushPolicy.TryParse method handles the string-to-enum conversion, validating inputs against the four modes while supporting numeric strings for fixed intervals.

Configuration Examples

Configure the environment variable before starting your OfficeCLI session:

# Adaptive auto-flush (default behavior)

export OFFICECLI_RESIDENT_FLUSH=auto
officecli open document.docx
officecli set document.docx '/p[1]' --text "Immediate"

# Persists to disk 2-10 seconds after command completion

# Flush every mutation synchronously

export OFFICECLI_RESIDENT_FLUSH=each
officecli add report.docx '/body' --text "Data"

# File updated on disk before CLI returns

# Fixed 5-second idle delay

export OFFICECLI_RESIDENT_FLUSH=5
officecli set spreadsheet.xlsx '/sheet1/cell[A1]' --value "100"

# Auto-saves exactly 5 seconds after last activity

# Disable auto-flush for manual control

export OFFICECLI_RESIDENT_FLUSH=off
officecli set presentation.pptx '/slide[1]/title' --text "Draft"
officecli save presentation.pptx  # Explicit persistence required

Summary

• OFFICECLI_RESIDENT_FLUSH controls when the resident server serializes in-memory documents to disk.
• Valid modes are each (every command), auto (adaptive 2–10s), <N> (fixed seconds), and off (manual only).
• The variable is parsed during static initialization of ResidentServer and stored in FlushMode/FixedFlushInterval.
• Legacy fallback to OFFICECLI_RESIDENT_IDLE_SAVE_SECONDS maintains backward compatibility.
• Choose each for pipeline reliability where external tools read after every command, or auto for optimal background performance.

Frequently Asked Questions

What happens if I don't set OFFICECLI_RESIDENT_FLUSH?

OfficeCLI defaults to auto mode, which uses an adaptive algorithm to flush the resident 2–10 seconds after activity ceases. This balances immediate availability with I/O efficiency by calculating the delay based on the exponential moving average of previous save durations.

Can I use OFFICECLI_RESIDENT_FLUSH in CI/CD pipelines?

Yes. For CI/CD pipelines where subsequent steps depend on file modifications being visible on disk, set OFFICECLI_RESIDENT_FLUSH=each to ensure every mutation is persisted before the command returns, eliminating race conditions between OfficeCLI and downstream tools.

Does OFFICECLI_RESIDENT_FLUSH affect the resident server's memory usage?

Indirectly. In off mode, the resident accumulates changes only in memory until explicit closure, potentially increasing memory footprint for large documents. The each and auto modes periodically serialize and release buffers, maintaining predictable memory consumption according to the save schedule.

Where is the flush logic implemented in the source code?

The parsing logic resides in src/officecli/Core/ResidentFlushPolicy.cs (lines 5–15), while the runtime state and adaptive EMA calculation are implemented in src/officecli/ResidentServer.cs (lines 57–68 and 123–142).

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