Session Persistence

Codemux keeps your work alive across app close and reopen at three layers:

1. The agent process itself keeps running after you close the app.
2. Scrollback is serialized to disk and restored on reopen.
3. Agent session resume picks up the conversation context for supported agents.

Agents Survive App Close

Every shell Codemux spawns runs inside a long-lived background process (codemux pty-daemon) instead of as a direct child of the app. When you close the Codemux window, the agent keeps running. When you reopen, Codemux adopts the running daemon and reattaches your panes to the live sessions — output continues flowing into the same xterm where it left off.

This is the default and there is no setting to toggle. If a regression ever ships, the escape hatch is the environment variable CODEMUX_DISABLE_PTY_DAEMON=1, which forces every PTY spawn back to the in-process path.

The daemon is also graceful: if it can't spawn, can't bind its socket, or hits any other failure, Codemux falls back to in-process PTYs so the terminal always works. A crash circuit-breaker caps respawn attempts at 3 failures per 60 seconds.

This same daemon is the foundation for Remote Hosts — pushing a workspace to an SSH host swaps the local socket for a tunnel; the rest of the architecture is unchanged. Your agent conversation comes with the workspace, too: see Your conversation follows the workspace.

Scrollback Save & Restore

When a pane closes or the app shuts down, Codemux serializes the terminal's scrollback buffer to disk. On reopen, the saved output is written back into the terminal so you see exactly what was on screen before.

A ── session restored ── marker separates restored content from new output.

Auto-Resume for Agents

For supported agents, Codemux goes beyond restoring scrollback — it resumes the agent session itself. Claude Code sessions automatically pick up where they left off using the --resume flag with the saved session ID.

This means closing and reopening a workspace doesn't lose your agent conversation. The agent continues with its full context intact. Combined with the persistent daemon above, the agent is genuinely still running — not re-spawned with restored state.

Session Adapters

The adapter system determines how different tools are detected and resumed. Adapters are configured in ~/.config/codemux/session-adapters.toml.

Each adapter defines:

• detect_pattern — Regex matched against the command that launched the pane
• resume_command — Template for the command that resumes a session, with {capture} placeholders
• capture_patterns — Regexes applied to PTY output to extract session IDs and other state

The default configuration ships with a Claude Code adapter. You can add adapters for any tool that supports session resumption.

Example Adapter

[adapters.claude]
detect_pattern = "\\bclaude\\b"
resume_command = "claude --resume {claude_session_id}"
validate_command = "claude --version"

[[adapters.claude.capture_patterns]]
name = "claude_session_id"
pattern = '"sessionId":"([^"]+)"'

Shift+Click Preset

Hold Shift and click a preset button to open it in a new split pane instead of creating a new tab. This lets you quickly launch a second agent side-by-side with an existing session.

Settings

Two settings control session persistence in Settings > Terminal: