[FEATURE] Add automatic garbage collection for ~/.claude cache directories

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 accumulates data in ~/.claude/ with no automatic cleanup, TTL, or size cap. Over normal usage (~3 weeks, ~460 sessions), my .claude directory grew to 1.7 GB silently:

| Directory | Size | Contents |
|-----------|------|----------|
| projects/ | 924M | Conversation transcripts (.jsonl) — one per session, never pruned |
| debug/ | 537M | 971 debug trace files — append-only, no rotation |
| file-history/ | 51M | File edit snapshots — no max-age or cap |
| todos/ | 9.3M | Stale todo state from completed sessions |
| shell-snapshots/ | 6.3M | Shell state captures |
| paste-cache/ | 4M | Clipboard cache |

None of these directories have any built-in garbage collection, max-size limits, or TTL-based expiration. They grow unbounded until the user discovers the bloat and manually cleans up.

Proposed Solution

Any combination of:

1. Auto-rotation with TTL — Delete files older than N days (configurable, default 7-14 days) on startup
2. Max-size cap — When a directory exceeds a threshold (e.g., 100M), prune oldest files first
3. claude --gc command — Manual cleanup with sensible defaults and --dry-run support
4. Configuration — Allow users to set retention policies in settings:

``json
{
"cache": {
"maxAgeDays": 14,
"maxSizeMB": 500,
"autoCleanOnStartup": true
}
}
``

Current Workaround

Manual cleanup or a weekly cron job:

find ~/.claude/debug -mtime +7 -delete
find ~/.claude/projects -name "*.jsonl" -mtime +7 -delete
rm -rf ~/.claude/file-history/* ~/.claude/todos/* ~/.claude/paste-cache/*

Environment

• Claude Code version: v24.13.0
• OS: macOS (Darwin 24.6.0)
• Usage: ~460 sessions over ~3 weeks across one monorepo project