claude-code - 💡(How to fix) Fix [FEATURE] Selective session retention: allow pinning/bookmarking important sessions to prevent auto-cleanup deletion

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

• #62250, #59248, #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