[BUG] Session transcripts default to a location outside typical backup coverage, then auto-delete after 30 days — silent, permanent loss of project history

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Environment

• Claude Code: 2.0.54
• OS: macOS 26.5.1 (build 25F80)

Summary

Session transcripts (~/.claude/projects/<project>/*.jsonl) live under the home directory, not alongside the project/repo they belong to. Combined with the default cleanupPeriodDays: 30 auto-deletion, this results in silent, permanent loss of session history for anyone whose backup strategy doesn't include their full home directory — which is a very common setup (e.g. backing up ~/Documents via Time Machine, but not ~).

For a tool that's increasingly used for substantive engineering work, these transcripts aren't disposable cache — they can be the only record of design decisions, debugging context, and IP-relevant discussion for a project. Deleting them by default after 30 days, with no warning, in a location the user may reasonably not be backing up, is a data-loss footgun.

What happened

Two sub-project directories had all their session .jsonl files deleted automatically (evidenced by both project directories' contents changing at the identical timestamp, consistent with a single cleanup sweep). The sessions were from January/early February 2026, comfortably past the 30-day default. The user had no idea this cleanup was happening, and had no backup of ~/.claude since it's outside their normal backup scope (~/Documents only).

Adding to the confusion: sessions-index.json in each project directory was left behind, still listing the deleted sessions (id, first prompt, message count, timestamps) as if they existed. There's no in-product signal that the underlying transcript was garbage collected — you only discover it when you try to open the session and the referenced file is gone.

Compounding issues discovered while investigating

1. No officially supported way to relocate the storage location. CLAUDE_CONFIG_DIR exists in the codebase but is undocumented, and users report it doesn't fully redirect all state (referenced in #3833, #25762, #28808).
2. cleanupPeriodDays: 0, which per the settings schema should mean "no cleanup," instead disables transcript persistence entirely (#23710) — the opposite of what a user trying to preserve history would expect, and easy to hit by mistake.
3. No documented/official backup or export mechanism for transcripts.

What Should Happen?

Suggestions

• Document cleanupPeriodDays and its default prominently (README, first-run notice, or output when a cleanup actually deletes something) rather than only in the settings schema.
• Officially support and document a way to relocate ~/.claude (or at least ~/.claude/projects) to a user-chosen path, so it can live inside an already-backed-up directory.
• When cleanup deletes a transcript, also remove or mark its sessions-index.json entry so stale references don't linger.
• Consider defaulting new installs to a longer retention period, or surfacing an explicit one-time prompt about the retention policy and how to change it, given how consequential silent deletion is for this kind of data.

Error Messages/Logs

Steps to Reproduce

Use Claude Code longer than the auto-cleanup period :-)

Claude Model

Not sure / Multiple models

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.0.54 (Claude Code), on macOS 26.5.1 (build 25F80)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

_No response_