--- title: Keep computer awake while sessions are running (cross-platform) --- # Keep computer awake while sessions are running (cross-platform) ## What it is ### What problem this solves Omniscio runs Claude CLI sessions that can work for many minutes — or, with cron jobs, recipe runs, and overnight batches, for hours — without anyone touching the keyboard. If the computer follows its normal power settings and goes to sleep while a session is mid-turn, the OS suspends the CLI child process and freezes the in-flight request: the session stalls, and the user comes back to a job that quietly stopped making progress instead of one that finished. The usual workaround is to dig into the operating system's power settings and disable sleep globally — which then keeps the machine awake all the time, even when nothing is running. That wastes power and is easy to forget to undo. ### What Omniscio does When the user turns on **Settings → Performance → "Keep computer awake while sessions are running"**, Omniscio asks the operating system not to go to sleep **for exactly as long as at least one session is actively running**, and lets it sleep normally again the moment the last running session finishes. Concretely, Omniscio holds an Electron `powerSaveBlocker('prevent-app-suspension')` open while the count of sessions in the **running** state is one or more, and releases it as soon as that count drops to zero. It is fully automatic — there is no separate "start"/"stop" button; the toggle is the only control. The toggle is **on by default** — Omniscio exists to run long, often unattended jobs, and a machine that sleeps mid-turn freezes them, so protecting that in-flight work is the behavior that matches what the app is for. It stays cheap: the blocker is only ever held while a session is actually running and is released the moment the running count hits zero, so an idle machine sleeps normally. A user who prefers their computer's normal power behavior can turn it off in one click. ## Where to find it ### Where to find the toggle **Settings → Performance section** → **"Keep computer awake while sessions are running"** (on by default). It applies live — turning it off while sessions are already running releases immediately, and turning it back on takes hold immediately, with no restart required. ## How it behaves ### System sleep vs display sleep (the important distinction) This feature blocks **system sleep only** — it does **not** keep your screen on. The display can still dim and sleep on its normal schedule to save power. That is deliberate: the work Omniscio is protecting is headless (a background CLI process), so there is no reason to burn power lighting up a monitor nobody is looking at. The machine stays awake and working; the screen behaves normally. ### What counts as "running" The blocker is held whenever one or more sessions are in the green **running** status — the same definition the rest of Omniscio uses for "a session is actively working." Sessions that are idle, waiting on you (**needs you**), ended, paused, or snoozed do **not** hold the machine awake. Snooze does not change this: a snoozed session that is still genuinely running keeps the machine awake, because real work is in flight. Recipe and pipeline "lane" sub-sessions are covered too, transitively: every recipe run also has a top-level orchestrator session that stays in the running state for the entire run, and that orchestrator is counted — so while any lane is executing, the running count is at least one and the machine stays awake. ### Cross-platform behavior Unlike several neighboring Performance toggles (CPU cap, adaptive memory paging) which are Windows-only, this feature is **not** platform-gated: - **Windows** — reliable (backed by the Win32 `SetThreadExecutionState` API). - **macOS** — reliable (backed by IOKit power assertions). - **Linux** — best-effort. Electron implements sleep inhibition on Linux via the desktop environment's D-Bus idle-inhibition service, and not every desktop environment or headless session exposes one. On those setups the toggle is a no-op rather than an error. The user-facing helper text says so plainly ("on Linux it depends on your desktop environment") so a Linux user is not promised a guarantee the OS can't keep. ### Why these defaults - **On by default.** Omniscio's whole purpose is running long, often unattended jobs; a mid-turn sleep freezes them, so keeping the machine awake while work is in flight is the behavior that matches what the app is for. Because the blocker is held only while a session is running and released the instant the count hits zero, an idle machine still sleeps normally — the cost when nothing is running is zero. Users who prefer their normal power behavior can turn it off. (Laptop note: while a session runs on battery this also holds off sleep, so a user who runs unattended jobs on battery and wants them to sleep should turn it off.) - **System sleep only (not display).** Keeping the screen on would waste power for headless work and surprise users who expect their monitor to dim normally. - **Released at zero running sessions** (not on a timer). The machine returns to normal power behavior the instant work finishes, so it is never held awake "just in case." ## For agents ### How this is verified - **Unit (pure state machine)**: [tests/unit/services/keep-awake-manager.test.ts](../../tests/unit/services/keep-awake-manager.test.ts) — drives the reconcile logic with an in-memory fake blocker: blocks only when (enabled AND running > 0), short-circuits the running-count query while disabled, is idempotent across repeated reconciles, releases when the count hits zero or the setting flips off, re-arms if the OS dropped the blocker underneath it, and releases unconditionally on shutdown (`release()`). - **Unit (settings wiring)**: [tests/unit/services/settings-apply.test.ts](../../tests/unit/services/settings-apply.test.ts) — verifies that flipping the setting on or off triggers a reconcile, and that an unrelated settings change does not. - **Unit (default-on resolution)**: [tests/unit/services/keep-awake-enabled.test.ts](../../tests/unit/services/keep-awake-enabled.test.ts) — with the toggle **unset** the resolver returns `true` (so the on-by-default posture actually engages the blocker), returns `false` only for an explicit stored `false`, and `true` for an explicit `true`. Guards the exact trap that `getSettings()` returns raw config **without** merging defaults: a strict `=== true` on the unset value would leave a fresh install's blocker OFF at runtime while the UI (which merges defaults at the IPC boundary) shows the toggle ON. ### Implementation pointers - [src/main/services/keep-awake-manager.ts](../../src/main/services/keep-awake-manager.ts) — the pure reconcile state machine. Every dependency (the blocker, the enabled flag, the running count) is injected, so it is unit-testable without an Electron runtime. Holds one blocker; `reconcile()` recomputes hold-vs-release; `release()` force-releases on shutdown. - [src/main/services/keep-awake-service.ts](../../src/main/services/keep-awake-service.ts) — the impure wiring: constructs the singleton with the real `powerSaveBlocker`, the live running count (`countSessionsByStatus('running', …)`), and the persisted setting. `initKeepAwake()` subscribes to `SESSION_STATUS_CHANGED` and reconciles on every status change; `stopKeepAwake()` tears it down on shutdown. - [src/main/services/keep-awake-enabled.ts](../../src/main/services/keep-awake-enabled.ts) — the pure `keepAwakeEnabled(settings)` resolver the service's `isEnabled` calls. Falls back to `DEFAULT_SETTINGS.keepAwakeWhileSessionsRunning` (now `true`) because `getSettings()` returns raw config without merging defaults, so only an explicit stored `false` turns the feature off. Kept dependency-free (no electron/DB) so it is unit-testable in isolation. - [src/main/services/settings-apply.ts](../../src/main/services/settings-apply.ts) — reconciles the moment the toggle flips, so on/off takes effect without a restart. - [src/main/startup/registry.ts](../../src/main/startup/registry.ts) — registers `initKeepAwake()` as the `Keep-awake service` startup task (run via `runStartupTasks` at boot); [src/main/app/shutdown.ts](../../src/main/app/shutdown.ts) calls `stopKeepAwake()` during graceful shutdown. - [src/renderer/src/features/settings/PerformanceSettings.tsx](../../src/renderer/src/features/settings/sections/performance/PerformanceSettings.tsx) — the toggle definition in `PERFORMANCE_DEFINITIONS` (`settingsKey: 'keepAwakeWhileSessionsRunning'`). ## Related The other reliability guards Omniscio runs on your behalf — keeping panels warm, hiding panels you are not using, and pacing agent-initiated work so the machine stays responsive — are on the [Low power mode](low-power-mode.md) page and under the app's Performance settings. Unattended work that would be worst hit by a sleeping computer is described on scheduled jobs.