--- title: Save a session --- # 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](../../.claude/memory/contracts/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](../../src/shared/keybindings.ts) (key **B**, category `global`). The handler in [useKeyboardShortcuts.ts](../../src/renderer/src/hooks/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](../../src/renderer/src/stores/session-store.ts) follow the optimistic update pattern: `snapshotFourSlices()` → `patchLive()` → IPC call → `restoreFourSlices()` on failure. The service layer in [session-lifecycle-service.ts](../../src/main/services/session/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](../../src/renderer/src/features/dashboard/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-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-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-or-stop-a-session.md) — Pause vs Save: pause stops the CLI; save is just an organizational bookmark - [keyboard-shortcuts.md](keyboard-shortcuts.md) — B key binding for save/unsave toggle