---
title: Session state and restore
description: Understand what Herdr keeps live, restores after restart, replays from history, resumes through agent integrations, and hands off during updates.
---

Herdr has several state paths. They solve different problems.

## Live persistence

Normal detach keeps the Herdr server running. Panes, shells, agents, servers, tests, and command processes keep running inside that server.

Detach the client with `ctrl+b q`. Reattach later:

```bash
herdr
```

This is the strongest persistence path because the original processes never stop.

## Snapshot restore

If the Herdr server stops and starts again, the original pane processes are gone. Herdr restores the saved session shape: workspaces, tabs, panes, cwd, layout, and focus.

Snapshot restore does not preserve running shells, servers, tests, or arbitrary processes. Panes that cannot use a stronger restore path come back as new shells in their saved directories.

## Pane screen history replay

Pane screen history restores recent terminal contents after a full server restart. It restores what Herdr can show, not the old process.

This is off by default because pane output can include secrets, tokens, prompts, and command output. Enable it from Settings > Experiments > pane screen history or with:

```toml
[experimental]
pane_history = true
```

When enabled, Herdr stores saved pane history in `session-history.json` next to `session.json`. Treat the Herdr config/session directory like terminal history.

## Native agent session restore

Some agents can resume their own conversation sessions. Herdr can use official integration-reported session references to restart supported agent panes after a Herdr server restart.

This is enabled by default. Disable it with:

```toml
[session]
resume_agents_on_restore = false
```

Herdr only resumes panes that reported a native session reference through a current official Herdr integration.

After a client attaches and provides terminal size and theme context, Herdr resumes eligible restored agent panes across workspaces and tabs without waiting for each pane to be focused.

Native session restore requires these Herdr integration versions or newer:

| Agent | Minimum Herdr integration version | Resume command |
| --- | --- | --- |
| Pi | `2` | `pi --session <path-or-id>` |
| Claude Code | `5` | `claude --resume <id>` |
| Codex | `5` | `codex resume <id>` |
| Cursor Agent CLI | `1` | `cursor-agent --resume <id>` |
| GitHub Copilot CLI | `2` | `copilot --resume=<id>` |
| Droid | `2` | `droid --resume <id>` |
| Kimi Code CLI | `3` | `kimi --session <id>` |
| Qoder CLI | `2` | `qodercli --resume <id>` |
| OpenCode | `5` | `opencode --session <id>` |
| Kilo Code CLI | `1` | `kilo --session <id>` |
| Hermes Agent | `2` | `hermes --resume <id>` |

OMP integration version `2` reports agent state, but does not report native session references for restore.

Run `herdr integration status` to check installed integration versions. Reinstall outdated integrations with `herdr integration install <agent>`.

Unsupported, missing, invalid, duplicated, or stale session references restore as normal shells in the saved pane directory.

If native agent session restore applies to a pane, Herdr resumes the agent session instead of replaying saved pane history for that pane.

## Live handoff

Live handoff is for update and remote attach flows that need to replace a running Herdr server. It asks the old server to transfer live panes to the new server, so pane processes can keep running across the server replacement.

This is different from snapshot restore, pane history replay, and native agent session restore. Handoff tries to keep the current processes alive. The others reconstruct state after the old server has already stopped.

Live handoff is experimental and opt-in:

```bash
herdr update --handoff
herdr --remote workbox --handoff
```

Plain `herdr update` and plain `herdr --remote workbox` use the normal restart/stop flow by default.

`herdr update --handoff` only applies to installs managed by Herdr's own updater. Homebrew, mise, and Nix installs are updated through their package managers, so `herdr update` is disabled there and cannot perform live handoff.

## What Survives

| Case | Processes keep running | Layout returns | Recent screen returns | Agent conversation resumes |
| --- | --- | --- | --- | --- |
| Detach and reattach | Yes | Yes | Yes, from the live terminal | Yes, because the process never stopped |
| Server restart | No | Yes | Only with pane screen history | Only with native agent session restore |
| Update without `--handoff` | Compatible servers keep running; restart-required servers may need stop/restart | Yes after restart | Only with pane screen history | Only with native agent session restore |
| Update with `--handoff` | Best effort for supported running servers | Yes | Yes, from the live terminal if handoff succeeds | Yes, because the process keeps running if handoff succeeds |
