Idle session release
Omniscio periodically releases the CLI process of a session that finished its turn and has been waiting on you past a threshold, reclaiming all of its memory. The conversation stays on screen; your next message brings it back transparently.
On this page
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.
Two things make a release happen sooner than your setting, and both stop at five minutes for the same reason — that is the point past which releasing costs nothing extra:
- Memory is under pressure. When the computer's commit charge approaches its limit, idle sessions are released at five minutes instead of fifteen, because only a release frees that memory.
- Sessions are waiting for a place. When the local session limit's line has anything waiting, a session that has finished its turn is released at five minutes too — a place is a live process, so the line cannot move until one goes. This one raises no notice: it is your queue draining, not a memory emergency.
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)
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
→ the auto-resume branch in session-service.ts,
which re-spawns with --resume. No new resume code, no new visible session state.
If that re-spawn cannot start — most often because Omniscio is updating Claude Code and the install is briefly unavailable — the session is left exactly as it was: it stays tracked and readied for its next message, and it is never marked failed over a condition that clears on its own. The wake or message runs as soon as the CLI answers again.
Eligibility (the pure isEligibleForIdleRelease predicate) releases a session
ONLY when ALL hold: it has a live process · the current turn has completed
(receivedResult — turn completeness, not the running status string) · no
recovery is in flight · it has not armed its own wait · no subagent is inside its
live patience window · no background command is still live · the DB row has NO
pending action · it's been idle ≥ the threshold by lastAgentMessageAt · and,
on Windows, the session's process tree holds nothing beyond what was running when
the process first started (checked last, only for a session that passed
everything else).
What is never released
- A supervised run's link (
supervised-run, 2026-10-30) — a cloud or own-box session whose agent runs on its box under the supervisor. Its local process is only an ssh client; ending it freed almost nothing and left the run working with nobody listening, so the final message never arrived. The account-switch kill skips these links too. - A session waiting on a question or a plan-approval (
pendingActionset) — its answer is delivered to the live process's stdio control channel, so it keeps its process. - A session that is mid-turn — judged by turn completeness (
receivedResult), never by therunningstatus string, and including a turn the CLI opened on its own (cliOpenedTurnAt, set at itssystem/initafter a background task finished, cleared by that turn's result) — recovering (auth / rate-limit / respawn / mid-turn-disconnect), holding a genuine prose wait or ScheduleWakeup (deferredWorkof any kind other than a[[OMNISCIO_HIBERNATE]]hold), with a subagent inside its live patience window (hasLiveSubagentWindow+SUBAGENT_PATIENCE_MS), or with a background command still live. - On Windows, a session whose process tree (its job object) holds a process
that was not there at the process's first
system/init— a test run, a detached shell, a Monitor command — or whose tree the app cannot read (no job, no recorded starting set, an empty or failed read). Doubt keeps the process. Both show inGET /diag/idle-releaseaslive-child-tree/tree-unreadable, and each new deferral writes one[idle-release] deferred sid=… reason=…line. macOS / Linux have no job object, so there this check does not run (T-390). The session's own background shell (its host, driver and parked spare process, started after the first message) is not counted as a leftover, as long as no command is running in it (T-14). - A
[[OMNISCIO_HIBERNATE]]hold is NOT a refusal (2026-09-27). It shareskind: 'agent_prose_wait'with a genuine prose wait, but its timer is a main-processsetTimeout, so killing the process does not lose it — the gate now tells the two apart by pattern id (isHibernationHold) and admits the hibernation hold. A genuine prose wait is admitted too, once the HOLD is ten minutes old (T-163, 2026-10-07) — see "A wait that was released still reads as Live".
A background task finishing wakes the session at once (2026-11-20)
When an agent ends its turn with "Waiting on a background process to finish" and the
background command later finishes, the Claude CLI starts a new turn by itself. That turn has
no assistant output for the first seconds — on a large context, often longer than the
sweep's one-minute interval — and receivedResult still reads true from the last turn. The
sweep used to read that as idle: the prose-wait hold was over ten minutes old and the
finished task no longer counted as live, so it killed the process about a second after the
turn began. The wake was lost and the session sat until the ETA check-in — measured on
2026-11-20 at 12:15:54 UTC (turn opened) → 12:15:55 (process released) → 12:40:42
(re-driven by the check-in), 25 minutes for a wake that should take seconds. A turn the CLI
opened now counts as mid-turn until its result arrives.
A wait that was released still reads as Live, not interrupted (2026-10-24)
Releasing an agent's process must never make that agent look broken to you.
A session that closed its turn on a genuine wait — "Waiting on a background process to
finish … ETA 180 minutes" — gives up its process once the hold is ten minutes old, and its
wake is re-driven later through --resume. The problem was what the app did in between: the
"has this agent stopped doing real work?" clock only advances when a turn actually runs a
tool, and the release had removed the only thing that could run one. So on a long wait the
clock was guaranteed to run out, and the session was pulled out of Live and reported to
you as interrupted with "it hasn't made progress in the last 120 minutes — it may be stuck"
— while its last message plainly said it was waiting. Reported by the owner 2026-10-24 11:40
about a session that had done exactly what it was told.
Now a wait the app freed is exempt from that judgement. At its deadline the app checks in with the agent instead, the check-in finds the process gone, and the session resumes itself. The exemption cannot hide a real stall, because it keys on the release mark the app itself set — a session the app never released (including one whose process simply ended, and a cloud run between turns) is judged exactly as before, and a chain that genuinely ran no tool for two hours still reaches you with "may be stuck". It also cannot loop: the resumed session clears the mark the moment it re-spawns, and the six-hour absolute ceiling still bounds the whole wait.
What you see when the app cannot reach the agent: the session still comes to you, but with the plain "Auto-wait timed out — no new activity for N minutes" line, never the "may be stuck" claim, because the app knows it was the one that stopped the clock.
Scope / no-op paths
idleSessionReleaseMinutes <= 0ORAMC_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.
Related
- 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).
- local-session-limit.md — the cap on how many sessions run at once; releasing an idle session's process is one of the ways a place in it frees up.
- Contract: idle-session-release-contract.md.
Last verified 2026-11-06