Session restore in cmux

Terminal workflows survive interruptions better when the app can reconstruct the shape of your work. cmux now treats the workspace layout as durable state instead of something tied to one app process.

The important boundary is live process state. cmux restores what it owns and what supported tools expose through their own resume APIs. It does not checkpoint arbitrary terminal processes.

What always comes back

After a normal relaunch, cmux restores the app-level session snapshot:

• Window, workspace, and pane layout
• Working directories
• Terminal scrollback, best effort
• Browser URL and navigation history

Agent sessions need hooks

Claude Code, Codex, OpenCode, Pi, Amp, Cursor CLI, Gemini, Rovo Dev, Copilot, CodeBuddy, Factory, and Qoder can resume when cmux has a native session ID. For most agents, install the integration with cmux hooks setup.

cmux hooks setup

The setup command installs supported agents whose binaries are on PATH and skips the rest. Claude Code is handled by the cmux Claude wrapper when Claude integration is enabled in Settings.

How it works

cmux writes a JSON session snapshot under Application Support with the window tree, workspace metadata, pane layout, terminal cwd, scrollback replay data, and browser navigation state.

Agent hooks write session mappings under ~/.cmuxterm. On restore, cmux rebuilds the UI first. If automatic agent resume is enabled, it launches each supported agent with that agent's native resume command and the saved session ID.

What stays out of scope

tmux, vim, shells, and unsupported tools reopen as normal terminals unless they have a cmux integration that records a safe native resume command. That keeps restore predictable and avoids replaying stale prompts or secrets.

Read the session restore docs for setup commands, supported agents, and troubleshooting.