Session sleep
Sleep retires idle panes without losing session identity. Ghostex supports manual sleep from the sidebar, bulk Sleep Inactive on project groups, Agent Auto Sleep policies, and click-to-wake sleeping placeholders.
What it is
A sleeping session is not closed — gxserver preserves its title, tags, resume command, and provider metadata. The terminal provider shuts down or detaches, the sidebar card fades, and the pane tab shows a sleeping placeholder.
Sleep frees GPU, CPU, and provider resources for sessions you are not actively using while keeping one-click restore. This is distinct from kill / close, which removes the session row.
Manual sleep & wake
- Session context menu → Sleep or Wake toggles a single row.
- Project header context menu → Sleep Inactive sleeps idle awake sessions in the group; Wake wakes all sleeping sessions.
- Sleep Below and Close Below target rendered rows beneath the clicked card across project groups.
- Command palette exposes Sleep Pet / Wake Pet when the floating pet overlay is configured.
- Context-menu Sleep waits for zmx provider shutdown — the row does not show sleeping until the host confirms state.
- Wake clears the local faded row immediately because it is reopening an existing sleeping record.
Sleeping pane placeholders
When a native pane tab is sleeping, Ghostex keeps the tab selected and visible with a Press Any Key to Wake placeholder instead of removing the tab chrome.
- clickToWakeSleepingSessions (default: true) — any key press on the placeholder wakes the terminal in place.
- Sleeping tabs participate in Cmd+Tab / Cmd+Shift+Tab pane tab traversal; selecting a sleeping tab applies the same wake logic as clicking it.
- Background sleep, close, and auto-sleep preserve the focused pane/tab instead of pulling focus to another session.
- The focused agent session is always excluded from Agent Auto Sleep.
Agent Auto Sleep
Settings → Auto Sleep configures idle timers per pane type. When enabled, Ghostex retires idle sessions through their native sleep paths after the configured minutes of inactivity.
| Option | What it does |
|---|---|
autoSleepCodeEditorEnabled | VS Code / code-server panes (default: true, 15 min) |
autoSleepGitEditorEnabled | Git editor panes (default: true, 15 min) |
autoSleepProjectEditorEnabled | Project board / Kanban panes (default: true, 15 min) |
autoSleepBrowserSessionsEnabled | Browser panes (default: false, 30 min) |
autoSleepAgentSessionsEnabled | Agent terminal sessions (default: false, 15 min) |
autoSleepRequireAgentResumeCommand | Only auto-sleep agents that have a resume command (default: true) |
autoSleepFavoriteAgentSessions | Include favorited agent sessions in auto-sleep (default: false) |
Idle thresholds accept 5, 10, 15, 30, 60, 120, or 300 minutes per category.
Auto Sleep behavior details
- Agent Auto Sleep waits when zmx title-observer health is starting, retrying, or failed — unavailable working-status detection is not treated as idle.
- Sleep Inactive on a project group includes idle zmx-backed command terminals while keeping working or attention sessions awake.
- Terminals with active Delayed Send timers stay awake until the scheduled send fires.
- Project Sleep Inactive, Wake, and Reload actions include idle zmx-backed command terminals.
- Favorite/pinned sessions are skipped unless autoSleepFavoriteAgentSessions is enabled.
CLI commands
| Option | What it does |
|---|---|
ghostex sleep <selector> | Sleep one session by id, alias, or quoted title |
ghostex sleep all | Sleep every listed session |
ghostex wake <selector> | Wake one sleeping session |
ghostex wake all | Wake every sleeping session |
ghostex sleep --session-id <id> --json | Mobile/SSH flag form; JSON exit status for automation |
ghostex sleep-session <id> true|false | Bridge action for UI automation |
Tips
- Enable Agent Auto Sleep if you run many concurrent agents — start with 30–60 minutes to avoid interrupting long tasks.
- Leave autoSleepRequireAgentResumeCommand enabled so auto-sleep never retires a session you cannot restore.
- Use Sleep Inactive at end of day on busy projects instead of closing tabs individually.
- If a session appears sleeping but the provider is still alive, use Wake then Sleep again — Ghostex defers sleep UI until provider shutdown completes.
- Sleeping sessions appear in ghostex sessions --json with lifecycleState sleeping; stopped rows are hidden by default.