# 세션 복원

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을 설치하세요:

```
# all integrations cmux can find on PATH
cmux hooks setup

# or one agent at a time
cmux hooks setup antigravity
cmux hooks setup codex
cmux hooks setup grok
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>` | 없음 |
| Campfire | `campfire` | `campfire --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, 브라우저 기록을 계속 복원합니다.

## 작동 방식

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

일반 [configuration docs](https://cmux.com/ko/docs/configuration)는 cmux.json을 다룹니다. 세션 복원은 app layout을 Ghostty 터미널 렌더링 설정과 분리해 저장합니다.

Canonical: https://cmux.com/ko/docs/session-restore

Documentation index: https://cmux.com/llms.txt