会话恢复

cmux 会保存你的工作形态，让应用重新启动时能带回相同的窗口、workspace、pane、终端上下文和浏览器状态。

cmux 会恢复什么

重新启动后，cmux 会恢复应用拥有的布局和元数据：

窗口、workspace 和 pane 布局
工作目录
终端 scrollback，尽力恢复
浏览器 URL 和导航历史

cmux 不会 checkpoint 任意实时进程状态。tmux、vim、shell 和未支持的终端应用会作为普通终端重新打开，除非它们有自己的 cmux resume 集成。

Agent 会话恢复

受支持的 AI coding agent 在 cmux 捕获到 agent 的原生会话 ID 后可以恢复。请在安装 agent CLI 后安装 hooks，确保二进制在 PATH 上：

cmux hooks setup
cmux hooks setup codex
cmux hooks setup grok
cmux hooks setup antigravity
cmux hooks setup omp
cmux hooks setup --agent opencode

cmux hooks setup 会安装它能找到的所有受支持集成，并打印被跳过 agent 的摘要。只需要一个集成时请指定 agent 名称。

自定义 surface resume 命令

高级用户和集成可以把任意终端 surface 绑定到重启命令。cmux 会保存通过公开 CLI 或 socket 创建的绑定，用于检查和手动恢复。

cmux surface resume set --kind tmux --checkpoint work --shell "tmux attach -t work"
cmux surface resume show --json
cmux surface resume clear --checkpoint work

已批准的前缀可在 Settings > Terminal > Resume Commands 中查看或编辑。cmux 只会自动运行被标记为可信的 resume 绑定，例如从运行中进程检测到的 tmux 绑定或用户批准的前缀。cmux 仍然不会 checkpoint 任意进程内存。令牌、密码、密钥和 API key 等敏感环境变量键会在保存恢复绑定前被丢弃。批准项也会绑定到工作目录以及存在时的精确环境变量值。

受支持的 agents

Agent	二进制	Resume 命令	Feed bridge
Claude Code	`claude`	`claude --resume <id>`	PermissionRequest
Codex	`codex`	`codex resume <id>`	PreToolUse, PermissionRequest
Grok / Grok Build CLI	`grok`	`grok -r <id>`	PreToolUse
OpenCode	`opencode`	`opencode --session <id>`	plugin event bus
Pi	`pi`	`pi --session <id>`	无
OMP	`omp`	`omp --session <id>`	无
Amp	`amp`	`amp threads continue <id>`	无
Cursor CLI	`cursor-agent`	`cursor-agent --resume <id>`	beforeShellExecution
Gemini	`gemini`	`gemini --resume <id>`	PreToolUse
Antigravity CLI	`agy`	`agy --conversation <id>`	PreToolUse, PostToolUse
Rovo Dev	`acli`	`acli rovodev run --restore <id>`	无
Hermes Agent	`hermes`	`hermes --resume <id>`	pre_tool_call, post_tool_call, pre_approval_request, post_approval_response
Copilot	`copilot`	`copilot --resume <id>`	PreToolUse
CodeBuddy	`codebuddy`	`codebuddy --resume <id>`	PreToolUse
Factory	`droid`	`droid --resume <id>`	PreToolUse
Qoder	`qodercli`	`qodercli --resume <id>`	PreToolUse

启用 Claude 集成时，Claude Code 由 cmux Claude wrapper 处理。Antigravity 也接受 agy 作为 setup 别名，Rovo Dev 接受 rovo。

手动恢复

cmux 正常启动时会恢复最后保存的 snapshot。你也可以手动重新应用上一个 snapshot：

History > Restore Previous App Launch
⌘ ⇧ O
cmux restore-session

关闭 agent 自动恢复

如需只恢复 pane 而不启动保存的 agent resume 命令，请关闭 Settings > Terminal > Resume Agent Sessions on Reopen 或设置：

~/.config/cmux/cmux.json

{
  "terminal": {
    "autoResumeAgentSessions": false
  }
}

这只会关闭 agent resume 命令。cmux 仍会恢复布局、工作目录、scrollback 和浏览器历史。

工作原理

cmux 会把带版本的 JSON snapshot 写入 ~/Library/Application Support/cmux/session-<bundle-id>.json，并保存一个 previous-session cache 供手动重新打开。
终端 scrollback 会作为有界文本保存，并在恢复时通过临时文件 replay。这是尽力恢复，因为终端应用可以重绘或清屏。
Agent hooks 会写入 ~/.cmuxterm/<agent>-hook-sessions.json，其中包含 agent 会话 ID、cmux workspace ID、surface ID、cwd、可用时的进程 ID，以及经过清理的启动命令。
恢复时，cmux 会先重建窗口和 pane。如果 agent 自动恢复已启用，它会启动一个一次性 shell 命令，用保存的会话 ID 运行 agent 的原生 resume 命令。

常规配置文档介绍 cmux.json。会话恢复会把应用布局与 Ghostty 终端渲染设置分开保存。