[FEATURE] Configurable Session Retention Policy

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code automatically deletes old session transcripts (.jsonl files) after a certain period, with no user-facing configuration to control this behavior. Users who rely on long-running or recurring sessions — such as multi-week infrastructure provisioning, phased migrations, or iterative debugging — lose the ability to resume or reference those sessions once the transcripts are purged.

Currently, there is no setting in settings.json, CLI flag, or /config option to adjust or disable session cleanup. The only workaround is manually backing up session files from ~/.claude/projects/, which is fragile and easy to forget.

Proposed Solution

Add a configurable session retention policy with the following options:

1. sessionRetention setting in settings.json (user-level and project-level):

``json
{
"sessionRetention": {
"maxAge": "90d",
"maxCount": 100,
"keepNamed": true
}
}
``

• maxAge: Duration string (e.g., "30d", "90d", "never"). Sessions older than this are eligible for cleanup. Default: current behavior. "never" disables age-based cleanup entirely.
• maxCount: Maximum number of sessions to retain per project. Oldest sessions are removed first when the limit is exceeded. 0 or null means no count-based limit.
• keepNamed: Boolean. When true, sessions that have been explicitly renamed via /rename are never cleaned up regardless of age or count limits. Default: true.

1. A CLI flag --keep when starting or resuming a session to mark it as permanently retained:

``bash
claude --resume <session-id> --keep
``

1. A /keep slash command within a session to mark it as retained on the fly.

Alternative Solutions

• Export command: A /export <path> command that saves the full session transcript to a user-specified location before it can be pruned. This is simpler but reactive rather than preventive.
• Symlink-based preservation: If a user symlinks a session file to another directory, skip cleanup for that file. Low implementation cost but poor discoverability.
• Retention tiers: Instead of a single policy, allow tagging sessions (e.g., important, archive) with different retention rules per tag.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

An Engineer uses Claude Code over several weeks to provision cloud infrastructure across multiple environments (dev, staging, production). Each phase builds on context from previous sessions — subscription IDs, naming conventions, module versions, resource dependencies, and decisions made during earlier runs.

When the engineer returns after a few weeks to continue provisioning or troubleshoot a deployment issue, the session transcript has been deleted. They cannot resume the session, and all accumulated context — including which resources were provisioned, which configurations were applied, and what issues were encountered — is lost. The engineer must reconstruct this context manually, which is time-consuming and error-prone.

With configurable retention, the engineer could set "maxAge": "never" or use /rename + "keepNamed": true to ensure critical sessions survive indefinitely.

Additional Context

• Session transcripts are stored as .jsonl files under ~/.claude/projects/<project-dir>/.
• The /rename command already allows users to name sessions, which signals intent to keep them. Honoring this signal by default would be a low-effort, high-value improvement.
• History entries in ~/.claude/history.jsonl survive longer than session transcripts, creating a confusing state where users can see evidence of past sessions but cannot resume them.
• This feature would complement the existing --resume and --continue flags, which are less useful when sessions are silently deleted.