Session persistence
Session persistence wraps Ghostty terminals in a named provider session so Ghostex can reattach after app restart, sleep, or remote attach from another device. zmx is the recommended default.
What it is
Without persistence (sessionPersistenceProvider: off), Ghostex launches agents and terminals directly in Ghostty. Closing the app or killing the process ends the session unless the agent CLI has its own resume mechanism.
With persistence enabled, Ghostex wraps new terminal and agent sessions in a named provider session (zmx, tmux, or zellij). The provider keeps the shell alive independently of Ghostex UI state. On wake or attach, Ghostex reconnects to the provider and replays the agent resume command when needed.
Providers
| Option | What it does |
|---|---|
off | Direct Ghostty launch — no provider wrapper |
zmx (recommended) | Default for new installs. Best for continuing Ghostex sessions from CLI, TUI, Android, and iOS |
tmux | Legacy provider; still accepted for existing sessions. tmuxMode setting mirrors this for compatibility |
zellij | Same durable session-name contract as tmux/zmx; hidden from Settings dropdown but still supported internally |
How persistence works
- Each persisted terminal exports GHOSTEX_SESSION_ID as the provider persistence name.
- Session rows store sessionPersistenceProvider and sessionPersistenceName (or legacy tmuxSessionName).
- gxserver tracks provider lifecycle: exists, missing, starting, and shutdown states.
- Attach prefers the live provider session when it still exists.
- If the provider session is gone but a resume command is saved, Ghostex recreates the named session and runs the agent resume command.
- zmx attach uses a shell wrapper that tries the exact resume command, then an optional fallback resume command.
# Simplified zmx wake path (conceptual)
zmx attach "$zmx_session" /bin/zsh -lc "$zmx_resume_launcher"Settings
| Option | What it does |
|---|---|
sessionPersistenceProvider | Global provider: off | zmx | tmux | zellij (default: zmx) |
tmuxMode | Legacy boolean mirror — true when provider is tmux |
showSessionIdInTerminalPanes | Show provider session id overlay in terminal panes (default: false, opt-in) |
autoSleepRequireAgentResumeCommand | Agent auto-sleep only when a resume command exists (default: true) |
Sleep vs persistence
Sleep shuts down the provider attachment while preserving session metadata and resume commands in gxserver. The sidebar row fades but remains restorable. Context-menu Sleep defers to zmx provider shutdown — Ghostex does not show a sleeping row while the provider is still alive.
Wake reattaches to the provider or recreates it. Waking zmx sessions no longer replays stale working/attention activity from the pre-sleep snapshot.
Passive restore keeps split panes and tab selection stable across reconnect, sleep, wake, close, and remote presentation updates.
Resume and attach
From the shell, ghostex attach (alias resume) resolves a session selector and:
- Uses the stored tmux, zmx, or zellij provider session when present and awake.
- Runs the supported agent resume command in the session project when provider metadata is missing.
- Starts missing zmx providers through gxserver before blocking interactive attach.
- Supports --session-id and --project-id for mobile and SSH remote attach.
ghostex sessions --json
ghostex attach --session-id G... --project-id P...
ghostex resume "My Session Title"Remote & mobile continuation
Android and iOS require zmx persistence on the Mac. ghostex android-check verifies settings and gxserver reachability.
Mobile clients call ghostex sessions --json over SSH for inventory and use ghostex attach --session-id, sleep --session-id, and wake --session-id for lifecycle actions. The TUI requests full zmx replay and syncs working/attention/idle status from persisted sessions.
CLI commands
| Option | What it does |
|---|---|
ghostex sessions | ls | List running and sleeping sessions (default hides stopped rows) |
ghostex sessions --json | Machine-readable inventory for mobile, TUI, and scripts |
ghostex attach | resume [selector] | Attach to provider or run resume command |
ghostex sleep | wake <selector> | Sleep or wake by alias, id, or all |
ghostex sleep --session-id <id> --json | Flag form used by Android sidebar actions |
ghostex kill <selector> | Close a session and tear down provider when applicable |
Tips
- Keep zmx as the provider if you use Android, iOS, or SSH attach — other providers may not pass android-check.
- Enable showSessionIdInTerminalPanes when debugging attach issues; the overlay shows the provider name Ghostex uses.
- Copy resume and Copy attach command in session context menus are hidden by default — enable them in Settings → Sidebar.
- Remote attach carrier projects use forceSessionPersistenceOff so hidden SSH panes do not pollute local persistence state.
- Internal Codex exec title-generation jobs use --ephemeral so they never become restorable persisted sessions.