工作階段還原

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，確保 binary 位於 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	Binary	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 終端機渲染設定分開保存。