Session Restore

coterm saves the shape of your work so relaunching the app can bring back the same windows, workspaces, panes, terminal context, and browser state.

What coterm restores

After relaunch, coterm restores app-owned layout and metadata:

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

coterm does not checkpoint arbitrary live process state. tmux, vim, shells, and unsupported terminal apps reopen as normal terminals unless they have their own coterm resume integration.

Agent session resume

Supported AI coding agents can resume when coterm has captured the agent's native session ID. Install hooks after installing the agent CLI so the agent binary is on PATH:

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

Running coterm hooks setup installs every supported integration it can find and prints a summary for skipped agents. Use an agent name when you only want one integration.

Custom surface resume commands

Advanced users and integrations can bind any terminal surface to a restart command. coterm stores public CLI and socket-created bindings for inspection and manual restore unless you approve a signed command prefix.

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

Review or edit approved prefixes in Settings > Terminal > Resume Commands. coterm only auto-runs resume bindings it marks trusted, such as live process-detected tmux bindings or user-approved prefixes. coterm still does not checkpoint arbitrary process memory. Sensitive environment keys such as tokens, passwords, secrets, and API keys are dropped before a resume binding is stored. Approved prefixes are also bound to the working directory and exact environment values when present.

Supported agents

Agent	Binary	Resume command	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>`	none
OMP	`omp`	`omp --session <id>`	none
Amp	`amp`	`amp threads continue <id>`	none
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>`	none
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 Code is handled by the coterm Claude wrapper when Claude integration is enabled in Settings. Antigravity also accepts agy as the setup alias, and Rovo Dev accepts rovo.

Manual restore

coterm restores the last saved snapshot on normal launch. You can also reapply the previous snapshot manually:

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

Disable automatic agent resume

To restore panes without launching saved agent resume commands, turn off Settings > Terminal > Resume Agent Sessions on Reopen or set:

~/.config/coterm/coterm.json

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

This only disables agent resume commands. coterm still restores layout, working directories, scrollback, and browser history.

How it works

coterm writes a versioned JSON snapshot to ~/Library/Application Support/coterm/session-<bundle-id>.json, plus a previous-session cache for manual reopen.
Terminal scrollback is stored as bounded text and replayed through a temporary file on restore. This is best effort because terminal apps can redraw or clear their screen.
Agent hooks write ~/.coterm/<agent>-hook-sessions.json with the agent session ID, coterm workspace ID, surface ID, cwd, process ID when available, and a sanitized launch command.
On restore, coterm rebuilds windows and panes first. If automatic agent resume is enabled, it launches a one-shot shell command that runs the agent's native resume command with the saved session ID.

The regular configuration docs cover coterm.json. Session restore keeps app layout separate from Ghostty terminal rendering settings.