# How OfficeCLI Auto-Resident Mode Handles the 60s Idle Timeout

> Discover how OfficeCLI auto-resident mode manages the 60s idle timeout. Learn about its RPC upgrade to 12 minutes for extended command access.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: internals
- Published: 2026-07-08

---

**OfficeCLI starts resident processes with a 60-second idle timeout, then upgrades them to 12 minutes via the `SendSetIdleTimeout` RPC when subsequent commands require extended access.**

The iOfficeAI/OfficeCLI repository implements an auto-resident mode that keeps documents in memory to accelerate subsequent operations. When a resident server first launches, it begins with a conservative 60-second idle timeout to prevent resource waste, then dynamically extends this window to approximately 12 minutes when users continue working with the file.

## The Initial 60-Second Idle Timeout

When you open a document using the `create` command with auto-resident enabled, OfficeCLI spawns a resident server process that maintains the document in memory. This initial instance is configured with a **short-lived idle timeout of 60 seconds**, ensuring that temporary operations do not leave orphaned processes consuming system resources.

If no further commands target the document within this window, the resident naturally terminates. However, when you invoke subsequent commands like `open` or `edit` that require the resident to persist, OfficeCLI upgrades the timeout to **720 seconds** (approximately 12 minutes) to support interactive workflows.

## Upgrading Timeouts via the Ping Pipe

The timeout upgrade is performed by `ResidentClient.SendSetIdleTimeout`, which communicates with the resident through a dedicated control channel. Unlike the main command pipe, which may be busy processing large operations, the **ping pipe** remains responsive for lightweight administrative requests.

In [`src/officecli/ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentClient.cs), the implementation constructs the pipe name by appending `-ping` to the resident's base pipe name:

```csharp
// ResidentClient.cs – SendSetIdleTimeout (lines 26-45)
public static bool SendSetIdleTimeout(string filePath, int seconds)
{
    var pipeName = ResidentServer.GetPipeName(filePath) + "-ping";
    using var client = new NamedPipeClientStream(".", pipeName, PipeDirection.InOut);
    client.Connect(200);                               // small connect timeout

    var request = new ResidentRequest { Command = "__set-idle-timeout__" };
    request.Args["seconds"] = seconds.ToString();      // e.g. 720 seconds
    var json = System.Text.Json.JsonSerializer.Serialize(request,
                     ResidentJsonContext.Default.ResidentRequest);
    PipeWriteLine(client, json);                       // send RPC

    var responseLine = PipeReadLine(client);
    if (responseLine == null) return false;

    var response = System.Text.Json.JsonSerializer.Deserialize<ResidentResponse>(
                       responseLine, ResidentJsonContext.Default.ResidentResponse);
    return response != null && response.ExitCode == 0; // success?
}

```

The method uses a **200-millisecond connect timeout** and sends an RPC request with the `__set-idle-timeout__` command, setting the `seconds` argument to the desired duration.

## Detecting Residents and Extending Timeouts

Before attempting to extend the timeout, OfficeCLI checks whether a resident is already running. According to the source code in [`src/officecli/ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentClient.cs), the `TryConnect` method (lines 12-40) verifies the resident's existence before `SendSetIdleTimeout` is invoked.

The workflow proceeds as follows:

1. **Detection**: `open` or `edit` commands call `ResidentClient.TryConnect` to check for an existing resident.
2. **Extension**: If found, the command calls `SendSetIdleTimeout` with **720 seconds** (12 minutes).
3. **Update**: The resident receives the `__set-idle-timeout__` command on its ping pipe, updates its internal idle timer, and replies with `ExitCode 0`.
4. **Persistence**: The resident now remains alive for the extended duration, preventing premature shutdown after the original 60-second limit.

```csharp
// Simplified detection and extension logic
if (ResidentClient.TryConnect(filePath, out _))
{
    // Resident already running – extend its idle timeout
    ResidentClient.SendSetIdleTimeout(filePath, 720); // 12 min
}
else
{
    // No resident – start a short-lived one (60s timeout)
    // This is handled automatically by the `create` command
}

```

## Fallback Behavior When RPC Fails

If the resident is not running or the RPC call fails, `SendSetIdleTimeout` returns `false`. The caller proceeds without the extended timeout, and the short-lived resident naturally exits after 60 seconds of inactivity. This graceful degradation ensures that commands do not hang waiting for unresponsive processes.

You can also manually extend the timeout using the command-line utility:

```csharp
// Command-line utility example
// $ officecli set-idle --seconds 900 <path-to-doc>
bool ok = ResidentClient.SendSetIdleTimeout("<path-to-doc>", 900);
Console.WriteLine(ok ? "Idle timeout extended" : "Failed to contact resident");

```

## Summary

- OfficeCLI auto-resident mode launches with a **60-second idle timeout** to conserve resources during temporary operations.
- The `ResidentClient.SendSetIdleTimeout` method in [`src/officecli/ResidentClient.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/ResidentClient.cs) extends this to **720 seconds (12 minutes)** via the ping pipe when users continue working.
- The **ping pipe** architecture ensures timeout updates succeed even when the main command pipe is busy.
- If the RPC fails, the method returns `false` and the resident exits after the original 60-second window.

## Frequently Asked Questions

### Why does OfficeCLI use a 60-second initial timeout instead of starting with 12 minutes?

The 60-second initial timeout prevents resource waste when users perform single, transient operations. According to the iOfficeAI/OfficeCLI source code, this short-lived default ensures residents terminate quickly if the user does not continue interacting with the document, while the upgrade mechanism provides flexibility for extended workflows.

### What is the ping pipe and why is it separate from the main command pipe?

The ping pipe is a lightweight control channel created by appending `-ping` to the resident's pipe name. It remains responsive even when the main command pipe is busy processing large document operations, guaranteeing that timeout adjustment requests complete without contending with the resident's normal command queue.

### How long does the resident stay alive after running an open command?

After detecting an existing resident and invoking `SendSetIdleTimeout`, the process remains alive for **720 seconds** (approximately 12 minutes) of inactivity. This extended window accommodates interactive editing sessions while still ensuring eventual cleanup.

### What happens if the timeout extension RPC fails?

If `SendSetIdleTimeout` returns `false`—due to the resident terminating prematurely or the named pipe connection failing—the calling command proceeds without the extended timeout. The resident continues with its original 60-second idle window and naturally exits if no further activity occurs.