Save a session

What it is

Saving a session bookmarks it into a collapsible Saved section in the sidebar, between Snoozed and Archived. The session keeps its current status (running, ended, needs you, etc.) — saving is an orthogonal organizational flag (saved_at timestamp), not a status change. It's the equivalent of starring an email: mark it for easy access later without changing what the session is doing.

One exception — attention wins over the shelf. If a saved session needs you (it goes needs_you, error, or stalled), it surfaces in the Needs You section instead of the Saved shelf, and drops back to Saved once you've handled it. This matches the inbox/badge count and the auto-advance ("next session that needs you"), which always counted a saved session as needing you — so a saved session can't ask you a question and then hide in a collapsed shelf. (Membership of both sections routes through the shared isSavedSectionMember predicate; see saved-sessions-contract.md I4.)

Save is the right action when you want to keep a session visible and easy to find — a reference conversation you check often, a long-running session you don't want buried in a growing list, or work you intend to come back to. It's NOT pause (which stops the CLI), NOT snooze (which hides until a time), and NOT archive (which moves it out of the active view).

Saved sessions that are not currently demanding attention appear dimmed (opacity 80%) in the Saved section, sorted by save time (most recent first). The section is collapsible and defaults to collapsed. Unsaving a session moves it back to the regular session list.

Where to find it

How to use it

1. Save via keyboard shortcut. Press B with a session active (no input focused). The session moves to the Saved section and a 5-second undo toast appears. If the session was snoozed, saving it clears the snooze first (you can't be both snoozed and saved — saving wins).
2. Save via the right-click context menu. Right-click any session row in the sidebar. The context menu shows Save (bookmark icon) between Snooze and the move-to submenu. Selecting more than one row changes the label to Save N sessions. The Save option is hidden for archived sessions (unsave an archived session by unarchiving it first).
3. Unsave via keyboard. Press B again on a saved session — the shortcut toggles. The session returns to the regular list with an undo toast.
4. Unsave via the context menu. Right-click a saved session — the menu shows Unsave (bookmark-minus icon) instead of Save.
5. Archiving clears saved. If you archive a saved session, the save flag is automatically cleared. Unarchiving does NOT restore the save — you'd need to save it again.
6. Navigate saved sessions. When the active session is in the Saved section, arrow-key navigation (J/K) walks the saved list instead of the regular list, matching the behavior of Snoozed and Archived navigation.
7. Mobile. The mobile sidebar mirrors the desktop: a collapsible Saved section appears between Snoozed and Archived with the same Bookmark icon and opacity dimming.

How it behaves

CLI control

Two routes on 127.0.0.1:19519 (apply-immediately, not approval-gated):

• POST /session/:id/save — Save a session. Returns 200 { ok: true, applied: true } on success; 409 if the session is archived.
• POST /session/:id/unsave — Remove a session from Saved. Returns 200 { ok: true, applied: true }.

Both are bearer-gated and share the 10/min mutation rate limit. No body required.

For agents

How it works

The saved_at column (nullable TEXT) on the sessions table stores an ISO timestamp when the session was saved, or NULL when not saved. This is the same pattern as snoozedUntil — a flag column orthogonal to status.

The keyboard shortcut is bound to the saveSession action in keybindings.ts (key B, category global). The handler in useKeyboardShortcuts.ts toggles: if the active session is saved, it unsaves; otherwise it saves. Both paths register an undo via registerSessionActionUndo().

The store actions saveSession() and unsaveSession() in session-store.ts follow the optimistic update pattern: snapshotFourSlices() → patchLive() → IPC call → restoreFourSlices() on failure.

The service layer in session-lifecycle-service.ts handles the save/unsave logic. saveSessionService() rejects archived sessions and clears any active snooze in a transaction before setting saved_at. unsaveSessionService() simply clears the flag. Both emit SESSION_STATUS_CHANGED push events.

The sidebar section in SessionsSidebar.tsx filters sessions through the shared isSavedSectionMember predicate (savedAt != null, not silently hidden, AND not currently needing attention — a saved session that needs the user is shown in Needs You instead, per saved-sessions-contract I4), sorts by savedAt descending, and renders them in a collapsible section with a Bookmark icon. The expansion state is tracked per-project in the savedExpandedByProject slice.

Related

• snooze-a-session.md — Snooze vs Save: snooze hides until a time; save keeps the session visible in a dedicated section
• archive-a-session.md — Archive vs Save: archive hides completely; save keeps it accessible. Archiving clears the save flag
• pause-or-stop-a-session.md — Pause vs Save: pause stops the CLI; save is just an organizational bookmark
• keyboard-shortcuts.md — B key binding for save/unsave toggle