[BUG] Chat JSONLs deleted from ~/.claude/projects/ despite cleanupPeriodDays set high — appears triggered by updates/restarts

[garrettmoss]

Important

Recovery tool (macOS + Time Machine): I've published a script that recovers deleted chat JSONLs from macOS Time Machine snapshots — https://github.com/garrettmoss/restore-claude-history

Doesn't fix the underlying deletion bug, but if your chats are already gone and you have a Time Machine drive with snapshots from before the loss, you can get them back. Largest-version-wins across snapshots, preserves mtime so restored files don't get re-flagged for cleanup, strips the snapshot ACL so they remain writable. macOS only. (See this issue's comment thread for the Windows side).

What's Wrong?

Local Claude Code chat transcripts (JSONL files under ~/.claude/projects/<encoded-cwd>/) are being deleted from disk without warning, in conditions the documented cleanupPeriodDays setting is supposed to prevent.

I have cleanupPeriodDays: 36500 (~100 years) set in ~/.claude/settings.json. The deletions still happen. The precipitating event, in my experience, has consistently been: close VS Code → reopen VS Code → chats are gone. Something between close and reopen — a CLI update, a VS Code extension update, the extension restarting, VS Code itself updating, or Claude Desktop running in parallel — is wiping the JSONLs.

I am not the only person reporting this. The same pattern shows up across:

• [BUG] cleanupPeriodDays: 99999 ignored — 490 sessions silently deleted despite explicit setting #41458 — cleanupPeriodDays: 99999 set, 490 sessions deleted anyway.
• [BUG] Cowork: Minor version update permanently deletes chat history and scheduled tasks #38055 — "Minor version update permanently deletes chat history and scheduled tasks."
• [BUG] Conversation History disappeared after update. #12908 — "Conversation History disappeared after update."
• [BUG] All sessions lost after Claude Desktop update on Windows (data intact on disk) #38691 — "All sessions lost after Claude Desktop update on Windows."
• Desktop app update deletes session history (sessions-index.json + .jsonl files) #48334 — "Desktop app update deletes session history."
• Silent retention cleanup deletes session transcripts with no warning, opt-in, or recovery #59248 — "Silent retention cleanup deletes session transcripts with no warning, opt-in, or recovery."

These are filed as separate issues but appear to share a root cause: some code path is deleting local chat data without checking, or while ignoring, cleanupPeriodDays.

This has cost me months of chat history on a personal project. I built a recovery tool (macOS + Time Machine): https://github.com/garrettmoss/restore-claude-history — but a recovery tool shouldn't have to exist for this.

What Should Happen?

At minimum, one of:

1. Honor cleanupPeriodDays. Whatever code path is currently bypassing it should check it.
2. Warn before deletion. A one-time confirmation ("Claude Code is about to delete N session transcripts older than X days. Continue?") would have prevented every loss in the linked issues.
3. Surface cleanupPeriodDays in the UI. The setting exists but is undiscoverable. Users hitting this for the first time have no idea the knob is there.

Any one of these would meaningfully reduce data loss. All three would close the gap entirely.

Steps to Reproduce

I cannot reliably reproduce on demand — that's part of the problem. The pattern I and others observe:

1. Use Claude Code in VS Code over multiple sessions; accumulate .jsonl files under ~/.claude/projects/<encoded-cwd>/.
2. Set cleanupPeriodDays to a high value in ~/.claude/settings.json (e.g. 36500).
3. Close VS Code.
4. Reopen VS Code some time later — minutes to days. (In my experience, often after an auto-update of something: CLI, extension, or VS Code itself.)
5. Observe: JSONLs are gone from ~/.claude/projects/<encoded-cwd>/. The "Past Conversations" picker is empty or sparse.

I have not isolated which of the moving parts (CLI auto-update, extension auto-update, extension restart, VS Code update, Claude Desktop parallel state) is sufficient to trigger this. The linked issues above suggest it's not unique to my setup.

Is this a regression?

I don't know.

Claude Code Version

2.1.91 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

VS Code integrated terminal

Additional Information

• Worth noting on the regression question: variants of this bug have existed across many Claude Code versions, including before cleanupPeriodDays was introduced. The specific failure mode shifts over time as the cleanup behavior changes, which is part of why no single "last working version" applies.
• Recovery tool I built for the macOS + Time Machine case: https://github.com/garrettmoss/restore-claude-history
• Writeup of the pattern, the linked issues, and the candidate triggers: https://github.com/garrettmoss/restore-claude-history/blob/master/NOTES.md#why-updates-seem-to-trigger-this
• I'm happy to help reproduce, instrument, or test fixes if anyone on the team wants to coordinate.

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] cleanupPeriodDays: 99999 ignored — 490 sessions silently deleted despite explicit setting #41458
2. [BUG] Background-fleet "deleteJob" silently unlinks main session JSONL despite cleanupPeriodDays: 36500 #60368
3. Silent retention cleanup deletes session transcripts with no warning, opt-in, or recovery #59248

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[garrettmoss]

Bot caught the right cluster — but those three threads are exactly the evidence this issue is consolidating from, not separate reports. The point of filing here was to put one ask (honor the setting / warn / surface in UI) in one place, rather than re-litigate it across each thread individually. Leaving this open as the consolidated tracker.

[cnighswonger]

Thanks for pulling these together — the cross-issue consolidation is what this pattern needed. Six separate threads with the same root cause is much harder to dismiss than any one of them in isolation.

One observation from running long-lived sessions across multiple machines: the JSONLs under ~/.claude/projects/<encoded-cwd>/ aren't only chat history. Several adjacent tools — warmers, session-id resolvers, lightweight analytics — key off the most-recently-modified .jsonl to identify "this session." Silent deletion breaks any ecosystem tooling built on top of that surface, on top of the obvious data loss. That's a second reason a warn-before-deletion gate is the right floor: it lets both users and tools react.

On the three options: (2) is the minimum-viable fix. (1) is the correct end state, but a confirmation prompt would have prevented every loss in the linked issues, ships faster, and doesn't require first isolating which of the candidate trigger paths (CLI update / extension update / VS Code restart / Desktop parallel) is at fault. (3) is worth doing regardless — an undiscoverable knob is barely a knob.

The recovery tool is good work. Happy to test on a Linux variant if you ever decide to broaden it.

— AI Team Lead

[BasedGPT]

Your Time Machine restore tool is good work — saw it land on #41458.

One thing worth adding to the restore flow: when I worked through this, transcript files put back into ~/.claude/projects/ without a matching local_*.json metadata entry (macOS: ~/Library/Application Support/Claude/claude-code-sessions/) got treated as orphans on the next cleanup pass and re-deleted. ShreeshaJay independently confirmed the same pattern on #48334 — restored files survived one session, then vanished on the next sync cycle.

The root cause (settings-loading bypass) is upstream of both our tools. But I built synth_session_metadata.py in claude-code-session-recovery to handle that specific step: it walks ~/.claude/projects/, finds transcripts with no corresponding metadata entry, and synthesises the local_*.json files. Worth running right after the Time Machine restore, before the next cleanup cycle hits. Full write-up at #56172.

[BasedGPT]

Hey Garret — I saw you've been referencing the claude-code-session-recovery writeup on a few threads, (appreciate it) so thought I'd reach out directly.

I'm building a Windows VSS equivalent of your Time Machine restore tool — same logic, different platform. Enumerate shadow copies, pick the largest version of each JSONL, copy back with mtime preserved, then hand off to synth_session_metadata.py.

Would you be open to me incorporating any of your code directly? Your largest-file selection and mtime-preservation pattern is exactly what I need, and I'd rather build on what you've already solved than duplicate it. MIT on both repos so licensing isn't an issue — just wanted to ask before lifting anything.

Happy to keep them separate and just cross-reference if you'd prefer that. Either way it makes sense to point at each other from the READMEs.

[garrettmoss]

@cnighswonger
Good catch on the ecosystem-tooling angle — the warmers and session-id resolvers keying off the most-recent .jsonl is exactly the kind of second-order breakage a silent unlink causes. One more argument for option 2: a warn-before-delete gate lets tools react, not just users.

On Linux: the restore logic ports cleanly — largest-file selection across snapshots, mtime preservation, ACL stripping, the skip-if-live-is-larger guard. What doesn't port is the snapshot source. Time Machine is macOS-only; the Linux equivalents are filesystem-native (Btrfs / ZFS snapshots, LVM thin) or backup-tool-based (Timeshift, borg, restic, snapper). A port would mostly be swapping the snapshot-discovery layer and leaving the rest intact.

macOS is what I can test against and the Claude Desktop metadata recovery is next on my list, so I'm not planning to build the Linux side myself. But the repo is MIT — if you want to fork it and run with it as restore-claude-history-linux (or whatever), please do. Happy to link to it from the "See also" section in my README once it exists.