SC26AI agents lab + dinner on the river · Nov 17
Parallel Works
View as Markdown
Share:

Sessions & Resume

Every pw code run creates a local session (a transcript of your conversation, the model used, and the workspace it ran in) stored on your machine. You can leave a session at any time and pick the conversation back up later, with the full history restored.

How Sessions Run

Sessions are hosted by a background service, the pw code daemon, which pw code starts automatically. Your terminal is a client of it, so quitting pw code only disconnects: a turn that is still running finishes in the background, and the exit message prints the command to reconnect. See The Background Daemon.

A session nobody is using is unloaded from the daemon after 30 minutes. This frees memory and closes its MCP servers; nothing is lost, and the next message or resume loads it again.

How Sessions Are Saved

Sessions are saved as one file per session under ~/.local/state/pw/code-sessions (the location respects XDG_STATE_HOME if set). Session IDs encode the start time plus a random suffix, for example 20260719-153045-a1b2c3d4.

A session in which you never sent a message is not listed and cannot be resumed, so launching pw code and quitting immediately leaves nothing behind.

Resuming a Session

# Resume the most recent session
pw code -r latest
 
# Resume a specific session by ID
pw code -r 20260719-153045-a1b2c3d4
 
# Pick a session from an interactive list
pw code --resume

If you do not specify a model when resuming, the session's original model is used. When you exit an interactive session, pw code prints the exact command to resume that conversation.

To browse every session on this machine, including ones still running, use the agents list (/agents, or ← at an empty prompt). To resume a session on another machine, use pw code attach.

The Session Picker

Running pw code --resume with no session ID opens an interactive picker listing your saved sessions, newest first. You can also open it from inside a running session with the /resume slash command.

The picker has four zones, the search box, Scope, Sort, and the list. Tab and Shift+Tab move between them. In the picker you can:

  • Filter as you type: The search box matches against a session's name, its first message, and its workspace path.
  • Toggle scope: By default only sessions from the current directory are shown; switch Scope to All with ←/→ to see every saved session.
  • Change sort order: Sort by last-updated (default) or creation time.
  • Preview a session: Press Ctrl+T to view the selected session's full history, rendered as it would appear on resume, before committing to it. Scroll with the arrow keys, press Ctrl+O to show or hide tool calls, Enter to resume, or Ctrl+T/Esc to go back to the list.
  • Expand details: Press Ctrl+G to show the selected session's workspace, model, timestamps, and message count.
  • Rename: Press F2 to rename the selected session.
  • Toggle density: Press Ctrl+O to switch between compact and comfortable row spacing.

Press Enter to resume the highlighted session, or Esc to leave the picker without resuming.

Naming Sessions

Sessions are named automatically from your first request, with a short title such as parser_test.go failures. To change it, run /rename <name> in the session, or press F2 in the picker. Bare /rename generates a fresh name from the conversation so far.

Resuming After a One-Shot Run

One-shot (non-interactive) runs are saved as sessions too, and print a ready-to-run resume command when they finish. The reverse also works: combine -r with -p to continue any saved session non-interactively. See Resuming a One-Shot Session.

Shared Home Directories

On clusters, your home directory, and with it the session store, is often shared by several login nodes. Only one machine runs a session at a time: a session that is live on another host is marked live on <host> in the picker and the agents list. If that host stops updating its claim for two minutes, for example because it crashed, the session can be taken over from another host.

Session Retention

Sessions are kept forever by default. Sweeping is opt-in: set the sessionRetentionDays setting to a positive number, and session transcripts that have not been touched within that many days are deleted. The daemon sweeps when it starts and every 6 hours after that.

ValueBehavior
0 (or unset, or any negative value)Sessions are kept forever (the default)
A positive numberSessions untouched for that many days are deleted

A session that is in use is never swept, and resuming a session restarts its retention clock. The window can also be changed from the Session retention row in /settings. See Settings for where to configure sessionRetentionDays.

Subagent transcripts

Transcripts of subagents are stored alongside their parent session and share its lifetime: they are cleaned up with the parent and revived together with it when you resume.

Local Sessions vs Account Chats

pw code sessions are stored only on your machine. They are not saved to your account and do not appear in the web Chat list. When you turn on remote control for a session, you can view and drive it from the web app's Agents page, but its transcript stays on your machine. Chats saved to your account are managed separately; the pw code overview lists the pw ai chats commands.

Related Documentation