세션 복원

cmux는 작업의 형태를 저장해 앱을 다시 실행했을 때 같은 창, workspace, pane, 터미널 컨텍스트, 브라우저 상태를 되돌릴 수 있게 합니다.

cmux가 복원하는 항목

재실행 후 cmux는 앱이 소유한 layout과 metadata를 복원합니다:

창, workspace, pane layout
작업 디렉터리
터미널 scrollback, best effort
브라우저 URL과 탐색 기록

cmux는 임의의 live process 상태를 checkpoint하지 않습니다. tmux, vim, shell, 미지원 터미널 앱은 자체 cmux resume integration이 없는 한 일반 터미널로 다시 열립니다.

Agent 세션 resume

지원되는 AI coding agent는 cmux가 agent의 native session ID를 캡처했을 때 resume할 수 있습니다. agent binary가 PATH에 있도록 agent CLI 설치 후 hook을 설치하세요:

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은 찾을 수 있는 모든 지원 integration을 설치하고 건너뛴 agent 요약을 출력합니다. 하나의 integration만 원하면 agent 이름을 사용하세요.

사용자 지정 surface resume 명령

고급 사용자와 integration은 어떤 터미널 surface든 restart 명령에 연결할 수 있습니다. cmux는 공개 CLI나 socket으로 만든 binding을 확인과 수동 resume용으로 저장합니다.

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

승인된 prefix는 Settings > Terminal > Resume Commands에서 확인하거나 수정할 수 있습니다. cmux는 실행 중인 프로세스에서 감지한 tmux binding이나 사용자가 승인한 prefix처럼 신뢰됨으로 표시한 resume binding만 자동 실행합니다. cmux는 여전히 임의의 process memory를 checkpoint하지 않습니다. 토큰, 비밀번호, 시크릿, API 키 같은 민감한 환경 변수 키는 resume binding을 저장하기 전에 제거됩니다. 승인은 작업 디렉터리와 정확한 환경 값이 있을 때에도 함께 묶입니다.

지원되는 agent

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 integration이 Settings에서 켜져 있으면 Claude Code는 cmux Claude wrapper가 처리합니다. Antigravity는 setup alias로 agy도 받고, Rovo Dev는 rovo를 받습니다.

수동 복원

cmux는 일반 실행 시 마지막으로 저장된 snapshot을 복원합니다. 이전 snapshot을 수동으로 다시 적용할 수도 있습니다:

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

Agent 자동 resume 끄기

저장된 agent resume 명령을 실행하지 않고 pane만 복원하려면 Settings > Terminal > Resume Agent Sessions on Reopen을 끄거나 다음을 설정하세요:

~/.config/cmux/cmux.json

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

이 설정은 agent resume 명령만 끕니다. cmux는 layout, 작업 디렉터리, scrollback, 브라우저 기록을 계속 복원합니다.

작동 방식

cmux는 versioned JSON snapshot을 ~/Library/Application Support/cmux/session-<bundle-id>.json에 쓰고, 수동 reopen을 위한 previous-session cache도 저장합니다.
터미널 scrollback은 제한된 텍스트로 저장되며 복원 시 임시 파일을 통해 replay됩니다. 터미널 앱이 화면을 다시 그리거나 지울 수 있으므로 best effort입니다.
Agent hook은 ~/.cmuxterm/<agent>-hook-sessions.json에 agent session ID, cmux workspace ID, surface ID, cwd, 가능한 경우 process ID, sanitize된 launch 명령을 씁니다.
복원 시 cmux는 먼저 창과 pane을 다시 만듭니다. agent 자동 resume이 켜져 있으면 저장된 session ID로 agent의 native resume 명령을 실행하는 one-shot shell 명령을 시작합니다.

일반 configuration docs는 cmux.json을 다룹니다. 세션 복원은 app layout을 Ghostty 터미널 렌더링 설정과 분리해 저장합니다.