# Restore and resume

> Resume tmux sessions after a crash or reboot: tmux-ide restore rebuilds windows, layouts and directories and reopens Claude Code, Codex and opencode chats.

If your tmux server crashes or your machine reboots, `tmux-ide restore` rebuilds
your tmux sessions from the last snapshot: windows, split layouts, working
directories and pane titles. With `--resume-agents`, Claude Code, Codex, Cursor
and opencode panes can reopen their previous conversation.

It works from a snapshot at `~/.tmux-ide/snapshot.json`, which the
[background updater](/docs/the-dock#the-background-updater) writes about every
30 seconds. The updater runs once any session is adopted or created from the
app, so a snapshot exists only if it was running before the crash.

## What restore rebuilds

```bash
tmux-ide restore
```

For each session in the last snapshot, restore rebuilds:

* every **window**,
* the **split layout** of each window,
* per-pane **working directories**,
* per-pane **titles**, and
* **re-adopts** the sessions that were adopted (their [tmux chrome](/docs/the-dock) returns).

If a session belongs to a project **with a workspace config**, restore relaunches
it from that config instead of rebuilding it from the snapshot.

## Preview and safety defaults

Restore never clobbers work in progress:

* An **already-live session** with the same name is skipped, never overwritten.
* Recorded pane **commands are not auto-run**. By default a rebuilt agent pane is
  a plain shell in the right directory with its title restored — you decide what
  to relaunch. Pass `--run-commands` to replay the recorded commands.

Preview the plan without touching tmux:

```bash
tmux-ide restore --dry-run
tmux-ide restore --dry-run --json
```

## Resume Claude Code and other agent conversations

Restore can also bring back agent **conversations**, not only the
panes. With `--resume-agents`, an agent pane that recorded an
`@agent_session_id` relaunches with that agent's resume command. You get the
conversation back instead of a fresh shell.

```bash
tmux-ide restore --resume-agents
```

You can make this the default in `~/.tmux-ide/config.json`:

```json
{
  "restore": {
    "resumeAgents": true
  }
}
```

### Support per agent

A pane resumes only when tmux-ide knows that agent's **resume command** and
captured the pane's **session id** while the agent ran. Support differs by agent:

| Agent                     | Resume invocation            | Session-id capture                                                           |
| ------------------------- | ---------------------------- | ---------------------------------------------------------------------------- |
| Claude Code               | `claude --resume <id>`       | automatic once `tmux-ide integration install claude` is set up (hooks)       |
| Codex CLI                 | `codex resume <id>`          | **automatic** — the updater reads the session's own rollout file             |
| Cursor CLI                | `cursor-agent --resume <id>` | **automatic** — the updater reads the CLI's chat store                       |
| opencode                  | `opencode --session <id>`    | automatic once `tmux-ide integration install opencode` is set up (plugin)    |
| Copilot CLI               | `copilot --resume=<id>`      | not automatic (no stable capture surface yet) — self-report works, see below |
| gemini, aider, goose, amp | —                            | no verified native resume invocation                                         |

Check what's active on your machine:

```bash
tmux-ide integration status
```

For an agent in the table whose id isn't captured automatically, such as
Copilot CLI, the agent can record its own id; it then resumes like the rest:

```bash
tmux set-option -p @agent_session_id <its-session-id>
```

Capture never overwrites: an id stamped by an integration (or by the agent
itself) is left alone. Codex/Cursor capture runs inside the chrome updater, so
it is active whenever any session is adopted.

## Snapshot cadence

How often the snapshot is written is part of the updater config in
`~/.tmux-ide/config.json`:

```json
{
  "updater": {
    "tickMs": 2000,
    "snapshotEvery": 15
  }
}
```

A snapshot is written every `snapshotEvery` ticks (default: every 15 ticks of
2s ≈ every 30 seconds). See [Configuration](/docs/configuration#other-sections).

## See also

* [Agent detection](/docs/agent-detection) — how `@agent_session_id` is recorded
* [Worktrees](/docs/worktrees) — isolated sessions per branch, restored too
* [Troubleshooting](/docs/troubleshooting#restore-finds-no-snapshot) — when there is no snapshot
* [CLI reference](/docs/commands) — every `restore` flag