Configured Retention 7 Days

Set chat transcript retention to seven days for privacy-conscious environments that require automatic cleanup of conversation history.

When to Use This Setting

Apply this setting when you need to:

• Comply with data minimization policies that require automatic deletion of AI conversation logs
• Reduce local storage consumption by pruning old Claude Code session transcripts regularly
• Maintain a clean workspace where only recent, relevant conversations are preserved

Consider alternatives when:

• You need to retain conversation history for long-term reference or audit compliance
• Your team relies on searching past Claude Code sessions for context on older decisions

Quick Start

Configuration

Copy
name: configured-retention-7-days
type: setting
category: cleanup

Example Application

Copy
claude setting:apply configured-retention-7-days

Example Output

Setting applied successfully. Configuration changes:
- cleanupPeriodDays: 7
- Transcript retention: 7 days
- Auto-cleanup: enabled on session start

Core Concepts

Retention Policy Overview

Aspect	Details
Retention Window	7 calendar days
Cleanup Trigger	Automatic on session start
Scope	Local chat transcripts and logs
Recovery	Not recoverable after deletion
Storage Impact	Significant reduction on active use

Retention Architecture

┌────────────────────────────────────┐
│         Session Timeline           │
│                                    │
│  Day 1  Day 2  ...  Day 7  Day 8  │
│  [kept] [kept]      [kept] [gone] │
│                                    │
│  ┌──────────────────────────────┐  │
│  │  Cleanup Process             │  │
│  │  1. Scan transcript dir      │  │
│  │  2. Compare file timestamps  │  │
│  │  3. Delete files > 7 days    │  │
│  │  4. Log cleanup summary      │  │
│  └──────────────────────────────┘  │
└────────────────────────────────────┘

Configuration

Parameter	Type	Default	Description
cleanupPeriodDays	number	none	Days to retain transcripts (7 in this preset)
cleanupOnStartup	boolean	true	Run cleanup when Claude Code starts
cleanupDryRun	boolean	false	Preview deletions without removing files
cleanupLogPath	string	none	Path to log cleanup operations
excludePatterns	array	[]	Session name patterns to exclude from cleanup

Best Practices

1. Run Dry Mode First - Enable cleanupDryRun before applying in production to see which transcripts would be deleted. This prevents accidental loss of important session histories and gives you confidence in the retention window.

2. Export Important Sessions Before Applying - Review your existing session history and export any transcripts you want to keep permanently. Once the 7-day window takes effect, older sessions will be automatically and irreversibly deleted.

3. Coordinate with Team Retention Policies - Ensure the 7-day retention aligns with your organization's data retention policy. Some compliance frameworks require specific minimum retention periods that may conflict with a 7-day cleanup window.

4. Monitor Storage Reclamation - Track how much disk space is reclaimed after enabling this setting. Active Claude Code users can generate substantial transcript data, and 7-day retention typically reclaims 70-80% of transcript storage.

5. Use Exclude Patterns for Critical Sessions - If certain sessions contain reference material you return to repeatedly, add their name patterns to excludePatterns. This preserves important context while still cleaning up routine sessions.

Common Issues

1. Important session deleted unexpectedly - The cleanup process is irreversible. Bookmark or export critical sessions before they age past the 7-day window. Consider using exclude patterns for sessions with names matching important projects.

2. Cleanup not running - The cleanup triggers on session startup. If Claude Code is kept running continuously without restart, old sessions accumulate. Schedule periodic restarts or configure a cron-based cleanup trigger.

3. Retention period too short for multi-week projects - Seven days may not be enough context for long-running feature development. Consider extending to 14 or 30 days for projects that span multiple sprints, or exclude specific project-related session patterns.