Automatic session cleanup silently deletes old chat transcripts (cleanupPeriodDays) with no warning or opt-in
Description
Claude Code runs an automatic retention/cleanup job that permanently deletes old session transcript files (~/.claude/projects/<project>/*.jsonl) once they exceed cleanupPeriodDays (default: 30 days). This happened to me with zero warning, in-session notice, or opt-in prompt — I only discovered it after the fact, when I went looking for several past sessions and found they were gone.
Impact
I lost multiple advanced sessions containing reasoning, design decisions, and context for in-progress work (e.g., an automated price-fetching/reconciliation workflow and several custom subagent setups) that I had not touched in over 30 days but still needed to reference. The deletion is a plain unlink — it does not go through the Recycle Bin (confirmed on Windows) and there is no trash/grace period, so recovery was not possible even via OS-level tools.
The only trace that a cleanup had happened was a timestamp in ~/.claude/.last-cleanup, which I found only while investigating after the fact — nothing surfaced this to me proactively before or after it ran.
Suggested improvements
- Before the first automatic cleanup ever runs for a user, surface a one-time, clearly visible notice (in-session and/or on startup) explaining the retention policy and how to change it via
cleanupPeriodDays. - After any cleanup run, print a short summary (e.g., "Deleted N sessions older than 30 days") instead of doing it silently in the background.
- Consider a short grace-period "trash" (e.g., move to
~/.claude/trash/for N days) instead of immediate permanent deletion, so an accidental/unwanted sweep is recoverable. - Document the cleanup behavior and
cleanupPeriodDaysmore prominently — e.g., surfaced in/configor during onboarding — since today the only way to discover it exists is to notice missing sessions afterward.
Environment
- Claude Code version: 2.1.251
- Entry point: VSCode extension (
claude-vscode) - OS: Windows 11