Session state and restore

Nagi has several state paths. They solve different problems.

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

The sections below explain each path.

Live persistence

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

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

nagi

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

Snapshot restore

If the Nagi server stops and starts again, the original pane processes are gone. Nagi 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 Nagi 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:

[experimental]
pane_history = true

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

Native agent session restore

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

This is enabled by default. Disable it with:

[session]
resume_agents_on_restore = false

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

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

Native session restore requires these Nagi integration versions or newer:

Agent	Minimum Nagi integration version	Resume command
Pi	2	pi --session <path-or-id>
OMP	3	omp --resume=<path-or-id>
Claude Code	6	claude --resume <id>
Codex	5	codex resume <id>
Cursor Agent CLI	1	cursor-agent --resume <id>
GitHub Copilot CLI	2	copilot --resume=<id>
Devin CLI	2	devin --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>
MastraCode	1	mastracode --thread <id>

Run nagi integration status to check installed integration versions. Reinstall outdated integrations with nagi 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, Nagi 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 Nagi 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:

nagi update --handoff
nagi --remote workbox --handoff

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

nagi update --handoff is retained in the inherited runtime, but Nagi’s automatic update channel is disabled until the project publishes signed artifacts. Rebuild reviewed source and restart the session instead.