---
title: Idle session release
---

# Idle session release

## What it is

**What:** A cross-platform feature that periodically **releases** (kills) the
persistent `claude` CLI process of a session that finished its turn and has been
waiting on you past a threshold — reclaiming **all** of its RAM (~250–450 MB
each), not just trimming the working set. The conversation stays on screen (it's
stored by Omniscio, not the process); your next message transparently re-spawns the
session via `--resume`, so the only difference is a slightly longer first reply
after a long idle. On by default.

**Setting:** `idleSessionReleaseMinutes` (number, default **15**, `0` = disabled)
— Settings → Performance, "Release idle sessions to reclaim more RAM". Hard kill
switch: `AMC_DISABLE_IDLE_RELEASE=1`.

A persistent Claude CLI child stays resident across turns (so MCP servers and
instant follow-ups survive). A session you got a reply from and walked away from
can hold 250–450 MB indefinitely; with many such sessions that is gigabytes of
pure waste. Releasing the process reclaims all of it, and the next message brings
it right back.

This is the harder/later sibling of the Windows-only working-set trim
(`wsTrimIdleMinutes`): trim de-faults pages but keeps the process alive; release
frees the whole process. Releasing after 15 min costs nothing extra — a session
idle that long has already lost its short-lived prompt cache, so its next reply
would reload regardless.

## Where to find it

There is nothing to open and nothing to switch on — it runs on its own. The only surface is the session pane itself, where a released session's next message takes a moment longer while it comes back.

## How it behaves

### How it works

A 60-second scheduler ([idle-release-scheduler.ts](../../src/main/services/idle-release-scheduler.ts))
asks `processManager.releaseIdleProcesses(thresholdMs, now)` to kill the
persistent process of every eligible session. The kill is **UI-silent** and
leaves the session in the already-handled "dead-persistent" state
(`childProcess=null, receivedResult=true`); the next user message hits the
dead-persistent guard in [user-message-router.ts](../../src/main/process/user-message-router.ts)
→ the auto-resume branch in [session-service.ts](../../src/main/services/session/session-service.ts),
which re-spawns with `--resume`. No new resume code, no new visible session state.

Eligibility (the pure `isEligibleForIdleRelease` predicate) releases a session
ONLY when ALL hold: it has a live process · is not mid-turn · its turn completed
· no recovery is in flight · it has not armed its own wait · no subagents are
running · the DB row has NO pending action · it's been idle ≥ the threshold by
`lastAgentMessageAt`.

### What is never released

- A session **waiting on a question or a plan-approval** (`pendingAction` set) —
  its answer is delivered to the live process's stdio control channel, so it keeps
  its process.
- A session that is **running / starting** (mid-turn), **recovering** (auth /
  rate-limit / respawn / mid-turn-disconnect), waiting on its **own ScheduleWakeup
  / prose-wait** (`deferredWork`), or has **subagents in flight**.

### Scope / no-op paths

- `idleSessionReleaseMinutes <= 0` OR `AMC_DISABLE_IDLE_RELEASE=1` → the scheduler
  tick returns early (feature off).
- Cross-platform — process kill works everywhere (unlike the Windows-only trim).
- No pre-warm on focus (yet): the reload happens on your next message ("a little
  longer in the background"), not when you open the session.

## For agents

### Source

- [src/main/process/idle-release-eligibility.ts](../../src/main/process/idle-release-eligibility.ts) — the pure eligibility predicate.
- [src/main/process/process-manager.ts](../../src/main/process/process-manager.ts) — `releaseIdleProcesses` / `getEligibleForRelease`.
- [src/main/services/idle-release-scheduler.ts](../../src/main/services/idle-release-scheduler.ts) — the 60s scheduler + kill switch + telemetry.

### Tests

- [tests/unit/process/idle-release-eligibility.test.ts](../../tests/unit/process/idle-release-eligibility.test.ts) — every release/skip rule + the idle boundary.
- [tests/unit/services/idle-release-scheduler.test.ts](../../tests/unit/services/idle-release-scheduler.test.ts) — threshold conversion, kill switch, observability, lifecycle.

## Related

- [session-memory-paging.md](session-memory-paging.md) — the Windows working-set CAP (a different lever: pages a busy session to disk instead of releasing an idle one's process).
- Contract: [.claude/memory/contracts/idle-session-release-contract.md](../../.claude/memory/contracts/idle-session-release-contract.md).