[FEATURE] Selective session retention: allow pinning/bookmarking important sessions to prevent auto-cleanup deletion

[macrogui]

Problem

Claude Code's current session cleanup mechanism (cleanupPeriodDays) is a blunt tool — it deletes all session JSONL files older than the configured period on startup, with no way to preserve specific sessions.

This creates a dilemma:

• Set a short period (e.g. 7-14 days) → disk stays manageable, but you lose potentially important sessions you may want to /resume later
• Set a long period (e.g. 90+ days) → important sessions survive, but disk usage grows unbounded (some sessions can be 3-5MB each)

There is currently no mechanism to:

• Mark a session as "important/pinned" to exempt it from auto-cleanup
• Automatically archive important sessions before deletion
• Set per-session or per-project retention policies

Current Behavior

• cleanupPeriodDays (default 30) deletes all JSONL files older than N days at startup
• /export allows manual export to Markdown, but this is a fully manual process — users must remember to do it before cleanup runs
• /compact reduces context window token usage but does not reduce on-disk JSONL file size

Proposed Solution

Add a session pinning/bookmarking feature with the following capabilities:

1. /pin slash command (or /bookmark, /save)

Mark the current session as important. Pinned sessions are exempt from cleanupPeriodDays auto-deletion.

User: /pin
Claude: Session pinned. This session will not be auto-deleted by cleanupPeriodDays.

Optionally with a reason/label:

User: /pin "engine-pricing-architecture-discussion"

2. /unpin to remove the pin

User: /unpin
Claude: Session unpinned. It will be subject to normal cleanup rules.

3. Pinned sessions indicator

• In /resume session list, show a 📌 icon next to pinned sessions
• In session metadata, store a pinned: true flag (with optional pinLabel and pinDate)

4. Pinned session management

User: /pinned
Claude:
  📌 "engine-pricing-architecture-discussion" — pinned 2025-05-28
  📌 "debug-atpco-rule-C1" — pinned 2025-05-15
  Total: 2 pinned sessions, 4.2MB

5. Disk-aware auto-archiving

When pinned sessions accumulate and total disk usage exceeds a threshold (e.g. 500MB), automatically:

• Compress pinned JSONL files (gzip)
• Or prompt the user to review and unpin old sessions

Implementation Details

The simplest implementation would be:

• Store pinned session IDs in a file like ~/.claude/pinned-sessions.json
• Before cleanupPeriodDays deletion, skip any session whose ID appears in the pinned list
• Expose /pin, /unpin, /pinned as new slash commands

// ~/.claude/pinned-sessions.json
{
  "pins": {
    "96df8b21-b25d-4121-8352-947bb31ad833": {
      "label": "engine-pricing-architecture-discussion",
      "pinnedAt": "2025-05-28T10:30:00Z"
    }
  }
}

Alternatives Considered

• Manually /export before cleanup — works but requires users to remember and act before cleanup runs; no automated safeguard
• Set very high cleanupPeriodDays — avoids deletion but causes unbounded disk growth
• External cron job — possible but fragile, doesn't integrate with Claude Code's session management
• Auto-export pinned sessions as Markdown on cleanup — could be an enhancement on top of pinning, but pinning is the foundational feature needed first

Related Issues

• Session transcripts silently deleted by cleanupPeriodDays (keyed on file mtime): data loss, no warning, no recovery #62250, Silent retention cleanup deletes session transcripts with no warning, opt-in, or recovery #59248, [BUG] Session transcripts silently auto-deleted after 30 days; sidebar shows ghost entries that error on click #62959 — focus on silent/unexpected data loss from cleanup, but don't address the need for selective retention
• The current issues all treat cleanup as a problem to be fixed (prevent unwanted deletion), but there's also a legitimate need to want cleanup while protecting specific sessions

[blain3white]

For a local workaround while this is being designed: I'm building Clean My Agent, which lets you selectively back up specific Claude Code sessions before the retention sweep runs.

[akirayamamoto]

Hit this one for real. I pinned a few conversations in Claude Code Desktop
expecting pinning to mean "keep these", and after a while the cleanup ran and
they were gone from my machine.

Pinning doesn't exempt anything from cleanupPeriodDays today, so this is exactly
the retention I was after. My expectation was simple: pinned should mean
never-expire. Right now there's no signal that a pinned session is still on the
chopping block.

Big +1 to the pin-exempts-from-cleanup behaviour in this issue.

[davidlovas]

Really want this. I just lost a month-long session of important, long-lived context work, plus about 200 others, to auto-cleanup. If I had been able to pin the handful of sessions that actually mattered, none of it would have happened.

Pinning, plus a hard guarantee that pinned sessions are never swept regardless of cleanupPeriodDays, updates, or restarts (see #41458 / #62272), would cover the real-world case. Worth prioritizing since it is the simplest reliable safeguard against the data-loss reports piling up (#62476, #59248, #62250).

[Ar9av]

Ran into this too — lost a long session to cleanupPeriodDays a while back before I knew to watch for it. Since there's no native pin/bookmark yet, I put together a small workaround: a /bookmark skill that writes the session id, cwd, and some tags to a local JSON file the moment you decide something's worth keeping, plus a tiny offline dashboard to browse them later (https://github.com/Ar9av/bookmark-agent). It doesn't stop cleanup from deleting the actual transcript, so it's not a real substitute for what's being asked here — just gives you a pointer to what a session was about and when, so you at least know what you lost / can --resume if it's still on disk. Hoping native pinning like what's proposed in this issue lands so this becomes unnecessary.