sessions: save and restore named session-list snapshots

[grimmerk]

The idea

Save the current set of sessions as a named snapshot, and later bring it back — either one session from it, or the whole set at once. The reference point is Session Buddy for browser tabs: you are not trying to keep everything open, you are trying to be able to put a working set down and pick it up again.

Why the existing tools do not cover it

CodeV already has three ways to keep a session findable, and none of them is this:

Mechanism	What it is good at	Why it is not a snapshot
Pins (#136, #137)	"this one matters long-term"	Flat and unbounded. 25 pins is already hard to read, and there is no notion of these five belong together.
Search (#132, #140)	finding a session you can describe	Requires remembering a distinguishing word. A working set is often "the four things I had open on Tuesday", which no query expresses.
Recency order	what you touched last	Decays. A set you put down two weeks ago is unreachable by scrolling.

A snapshot is the missing middle: a set, named, with a time, that survives being ignored.

Measured support for the gap, from the 2026-08-20 corpus survey: frecency ranking (the obvious "surface what matters" alternative) put only 3 of 7 real pins in its top 10, while three others ranked #26, #63 and #72. What people keep is not what they touch often — so an automatic ranking will not reconstruct a working set, and it has to be captured explicitly.

Sketch

• Capture: the visible session list, or a hand-picked subset, under a name.
• Restore: open one session from the snapshot, or launch/resume the whole set.
• Browse: snapshots listed with their name and capture time.

Open design questions

1. Does a snapshot store pin / hidden state too? Leaning yes, but stored beside the list rather than merged into it — a list records "what I was looking at", a pin records "this matters long-term", and merging them lets a restore silently rewrite pins.
2. What does "restore the whole set" mean when sessions are dead? A snapshot can outlive its transcripts (see sessions: resume fails for sessions whose transcript was cleaned up — detect and mark as expired #135 — resume fails once a transcript is cleaned up). Restoring probably has to report which members are gone rather than failing as a batch.
3. How does a snapshot survive /branch? A snapshot stores sessionIds, and /branch mints a new one for the same work — 23.9% of transcripts on disk carry forkedFrom (sessions: /branch creates generation chains — 23.9% of transcripts, and CodeV cannot tell them apart #142). Same failure mode as pin drift, and it wants the same answer: stable task identity across sessionIds, not per-feature patching. This is a reason to settle sessions: /branch creates generation chains — 23.9% of transcripts, and CodeV cannot tell them apart #142's C1 direction before building restore.
4. Where does it live? session-marks.json in ~/.config/codev/ already holds pins and hidden state with atomic temp+rename writes and an fs.watch reload. A snapshot store is the same shape of problem; whether it shares that file or gets its own is an implementation call, but it must inherit the same authority invariant — PR feat(sessions): pin browse modes — recency order, ungroup, pinned-only #137 spent four review rounds narrowing "when is a read authoritative", and a second store that re-derives it will re-derive it wrong.

Priority

High value, medium-to-large effort. Group B in #144, sequenced after the search work (group A) and gated on question 3 above.

🤖 On behalf of @grimmerk — generated with Claude Code

[grimmerk]

Sharper motivation than the issue currently states, and it changes what the first slice should be.

The trigger was a machine slowed to a crawl. That turned out not to be about terminals — measured 2026-09-05: iTerm2 itself was 368MB in one process, while 36 claude processes held 4.66GB (32 with a live TTY), against 20.4GB of 21.5GB swap in use and 22.6M pageouts. Several sessions had been up 7–17 days. Switching terminal emulator would reclaim the 368MB, not the 4.5GB.

The obvious advice — close the old tabs, CodeV lists sessions from history.jsonl regardless of whether a terminal is open, so nothing is lost — is wrong, and the reason is the point of this issue.

The open tabs are not only cost. They are the external representation of the working set: the half-remembered path back to something, the thing you glance at to double-check where you were. Closing them recovers memory and destroys that. So "close them first, build the feature later" asks for the cost up front and pays the benefit later.

Which inverts the sequencing: the capture half has to exist before the tabs can be closed.

First slice

• Capture: name the current set — or a hand-picked subset — and store it.
• Restore: nothing new required. Clicking a row already resumes a session, so a stored list plus the existing row action is a usable v1.
• Everything else in this issue (whole-set restore, snapshot browsing, pin capture) can follow.

That makes the first slice genuinely small, and it unblocks an action that is wanted today rather than being a feature for later.

Safety note for whoever builds it

Closing a session's terminal is safe for an idle session — the transcript is on disk and resumable — but not for one with in-flight background subagents, which follow the process (see #142). CodeV already shows working / idle status, so the information needed to close safely is on screen; the capture step should probably surface it at capture time rather than leaving the user to cross-reference.

Adjacent, and worth deciding together

#94 — a live-session view showing pid / tty / uptime / memory. The same measurement found 1 session registered in ~/.claude/sessions/ whose process was dead (a zombie row in the list) and 5 live processes with no registration (invisible as active). Capture answers "what was I working on"; #94 answers "what is actually running and what is it costing". They are complementary and both small; doing them in one pass is likely cheaper than either alone.

🤖 On behalf of @grimmerk — generated with Claude Code

[grimmerk]

What a captured member should store — and a better source than "the last assistant message".

A snapshot of bare sessionIds is close to useless for recall. What makes the list work is the material stored with each member, and the request that prompted this was to keep the last assistant message (possibly plus the last user message, budgeted by total size rather than count).

There is a better source, and Claude Code already writes it into the transcript:

{"type":"system","subtype":"away_summary","content":"…  (disable recaps in /config)"}

This is the one-line "where we are, what's next" recap shown at the bottom of the terminal. Measured across the corpus:

Sessions carrying at least one away_summary	74 of 88 — 84.1%
Length of the last one	median 251 chars, p90 290, max 322

It is strictly better suited than the last assistant message for this purpose: a final assistant turn is often a table fragment or a tool result, whereas the recap is written to answer exactly the question a snapshot is trying to answer. Extracting it costs one more pattern in the enrichment grep that already scans for custom-title, ai-title and pr-link.

Suggested per-member payload, in priority order, capped by total bytes rather than message count:

1. last away_summary (84% of sessions have one)
2. last user message
3. last assistant message
4. pin state at capture time (point-in-time; unpinning later must not rewrite the snapshot)

On reproducing what the terminal looked like

The motivation given was visual: the terminal's appearance is itself a memory aid, and the open question was whether the same content in a different layout still helps.

Pixel layout will not transfer — the popup has a different width, no ANSI colour, and a different type size, and imitating a terminal would cost a lot for a poor likeness. But layout is not what is doing the work. In the screenshots that prompted this, the recall-dense elements are semantic landmarks: the recap line, the task title, the branch name, PR numbers, the context percentage. Those survive re-rendering.

⇒ Render the same fields in the same order every time, and spend the effort on that consistency rather than on imitating the terminal. Stable ordering is itself the visual hook; a layout that reshuffles by content length is what would actually break recall.

🤖 On behalf of @grimmerk — generated with Claude Code

[grimmerk]

The model in this issue was imprecise, and the reference implementation is specific: Session Buddy for Chrome. Saving "the currently open set" is the feature — hand-picking a subset is a variation of it, not the core.

Also worth separating clearly, because they were being conflated: the working set / favourites idea is pins, which already shipped (§4.4 D1, PRs #136 and #137, modelled on Notion favourites). A session list is a different thing — pins are "this matters long-term", a saved list is "this is what was open on Tuesday".

The structure maps directly

Session Buddy	CodeV
TABS — the live windows	the sessions currently open — which is exactly #94's live view
COLLECTIONS — saved sets, each with a name and "Created N days ago"	saved session lists
Save	capture
Search tabs and collections	search must span live sessions and saved lists
"22 tabs" per collection	cheap, useful metadata worth copying

⇒ #94 and this issue are the top and bottom halves of one screen, not two adjacent features.

Four consequences

1. "Open" needs a definition, and today's data cannot answer it correctly. A Chrome tab is unambiguous. CodeV can only infer it from ~/.claude/sessions/<pid>.json. Measured 2026-09-05 across 33 real sessions: 1 was alive with no registration (claude -r on ttys017, up 2d13h) and 1 was registered with a dead process (pid 22290, left over from the /branch experiment in #142). So capturing "what is open" would silently omit one session and store one ghost.

⇒ #94 is a prerequisite, not an adjacent nicety.

(Correcting an earlier comment: it said 5 live processes were unregistered. Four of those were infrastructure — daemon run, bg-pty-host, bg-spare, and the app helper — not sessions. The real number is 1.)

2. Restore is asymmetric in a way Chrome's is not. Reopening 22 tabs is comparatively cheap. Resuming 22 sessions is 22 processes at roughly 145MB each — about 3.2GB. Since the motivation for this feature is memory pressure, copying Session Buddy's "open all" would rebuild the problem it was built to solve. Either omit whole-set restore, or show the projected cost before doing it.

3. A closed Chrome tab is gone; a closed session is not. The transcript stays on disk and stays resumable. So the value here is grouping and recall, not rescue — which makes the stored recall material (the away_summary recap, see the comment above) more important than in Session Buddy, and whole-set restore less urgent.

4. Search has to reach collections. Session Buddy searches "tabs and collections". CodeV search already spans every session, but a collection name is a new field — which lines up with the field-scoped syntax in #140 as one more scope (list:).

Open UI questions

• Where does this live? Session Buddy affords three sections via a left rail; a menu-bar popup has no such width. Two sections inside the Sessions tab, or a new tab?
• Should pins join the same screen (LIVE / COLLECTIONS / PINNED)? Keeping them apart means two separate notions of "saved things" in one app.

🤖 On behalf of @grimmerk — generated with Claude Code

[grimmerk]

How reliable is the recap? Measured, then checked against the documented behaviour — the two agree, and the answer is "very, but not unconditionally".

Coverage in the corpus (88 sessions)

Transcript size	With a recap		Last activity	With a recap
<0.1MB	8 / 21 — 38%		<1 day	32 / 33 — 97%
0.1–1MB	12 / 12 — 100%		1–3 days	1 / 5 — 20%
1–5MB	25 / 26 — 96%		3–7 days	3 / 5 — 60%
5–20MB	18 / 18 — 100%		7–14 days	26 / 26 — 100%
>20MB	11 / 11 — 100%		14–30 days	12 / 19 — 63%

Length decides it, not age. The right-hand column looks erratic only because each age bucket happens to contain a different number of stubs. Of the 14 sessions with no recap, 13 are 9–29 line stubs — opened, a few messages, abandoned.

Excluding stubs: 65 of 66 sessions ≥0.1MB carry one — 98.5%.

The documented conditions explain every case

Per Interactive mode, a recap is generated in the background once at least 3 minutes have passed since the last completed turn and the terminal is unfocused, only for sessions with at least 3 turns, never twice in a row, and capped at 400 characters. It is on by default and can be turned off in /config or with CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0. /recap produces one on demand.

• The 13 stubs never reached 3 turns — absent by design.
• The single substantial exception (4 hours, 523 lines, five gaps over 5 minutes, one of 135 minutes) still has none. The unfocused condition accounts for it: a gap is not the same as the window losing focus, and a transcript cannot distinguish "away from the keyboard with the window still frontmost" from "switched away". Not provable from the data, but no unexplained case remains. It ran on 2.1.252, newer than most recap-writing sessions here, so "too old a version" is ruled out.
• Longest recap measured: 322 characters, consistent with the 400 cap.

Three consequences for this issue

1. Use the recap as the primary, but a fallback is mandatory — it can be switched off by the user, needs 3 turns, and needs the window to have been unfocused. Falling back to the last user message covers the stubs, which is precisely where it is missing, and those sessions only have a few messages anyway.

2. Store the recap's timestamp and show it. Because a recap never appears twice in a row, a stored one can describe a state several turns old. Comparing it against the session's lastTimestamp reveals the lag — worth surfacing, since the recap ends with a "next action" and acting on a stale one is the failure mode.

3. The 400-character cap makes the layout predictable — the field cannot grow without bound, so the row budget can be fixed.

🤖 On behalf of @grimmerk — generated with Claude Code

[grimmerk]

Shipped in #147 (merged 2026-09-05): save what is on screen as a named list, browse and resume members in captured order, rename / delete, the recap on each member, and the live view this depends on. Staying open for the one piece #147 deliberately left out.

Remaining scope: open the members that are not running

#147 omitted "open all" because reopening a whole list blindly costs a process per session (~145MB each on the reference machine) — the very thing a saved list exists to relieve. Three real moments turn out to want exactly that, and in all three the cost is one the user is choosing on purpose:

1. After a reboot or a macOS update — restore the working set.
2. After closing every session to reclaim memory (or to confirm what was using it) — put the set back.
3. When switching terminal app (e.g. to Ghostty) — close the set in one app, reopen it in the other.

Constraints that make it safe rather than blind:

• Only members that are NOT running. Idempotent: pressing it twice does nothing the second time; a member already live is skipped, not duplicated. The live view's ps join is the source of truth for "running", not the registration files.
• Say the cost before doing it. The control reads like open 12 not running · ~1.7GB (projected from the mean RSS of the current live report, or a fixed estimate when none), and asks once.
• Stagger the launches (~300ms apart): opening twenty terminal windows in the same tick is rough on the terminal app and on the pid registrations.
• Use the current terminal setting, so "switch to Ghostty" is: change the setting, then press it.
• Members whose transcript is gone (sessions: resume fails for sessions whose transcript was cleaned up — detect and mark as expired #135) are reported, not launched.

Sits in group B of #144 (Decision 14 there).

🤖 On behalf of @grimmerk — generated with Claude Code