[BUG] No session file retention policy - files accumulate indefinitely causing degraded startup and eventual OOM #20429

Preflight Checklist

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

What's Wrong?

Claude Code has no session file retention or cleanup policy. Session .jsonl files in ~/.claude/projects/ accumulate indefinitely with no max count, no max age, no max total size, and no automatic pruning. For power users running multiple daily sessions across several projects, this results in:

1. Hundreds of session files per project (I had 108 in one project, 529 in another, 1,166 in another)
2. Gigabytes of session data (1.5GB+ total across projects, with individual files reaching 2.5GB)
3. Progressively degraded startup performance — Claude redlines the CPU for 2-3 minutes on every fresh start while indexing/scanning all session files
4. Eventual OOM crashes when the cumulative indexing load exceeds available memory

This is distinct from issues about individual large session files (#20367, #19025). Even with no single oversized file, the sheer volume of accumulated sessions causes Claude Code to grind on startup because it scans all .jsonl files to build/validate sessions-index.json.

What Should Happen?

Claude Code should have a built-in session retention policy, such as:

• Max session count per project (e.g., keep last 20-30 sessions)
• Max session file age (e.g., delete sessions older than 30 days)
• Max individual file size (e.g., cap at 50-100MB with compaction or truncation)
• Max total size per project (e.g., 500MB ceiling)
• Configurable retention settings in .claude/settings.json or similar

At minimum, startup indexing should be resilient — skip files over a size threshold, use streaming parsing, or defer indexing of old sessions.

Reproduction

On a system with heavy daily Claude Code usage across multiple projects:

# Check session file accumulation
find ~/.claude/projects/ -name "*.jsonl" | wc -l
# Result: 2,500+ files across projects

# Check total size
du -sh ~/.claude/projects/
# Result: 1.5GB+

# Check per-project counts
for d in ~/.claude/projects/*/; do
  count=$(ls "$d"*.jsonl 2>/dev/null | wc -l)
  size=$(du -sh "$d" 2>/dev/null | cut -f1)
  echo "$count files ($size) - $(basename $d)"
done

After 2-3 months of daily usage, fresh claude launches (no --resume) take 2-3 minutes of 100% CPU before becoming responsive, and eventually crash with OOM on resource-constrained systems.

Workaround

I wrote a cron job to enforce retention manually:

# Delete session files over 50MB (bloated/runaway sessions)
find ~/.claude/projects/ -name "*.jsonl" -size +50M -delete

# Keep only last 15 sessions per project
for projdir in ~/.claude/projects/*/; do
    count=$(ls "$projdir"*.jsonl 2>/dev/null | wc -l)
    if [ "$count" -gt 15 ]; then
        ls -t "$projdir"*.jsonl | tail -n +16 | while read f; do
            rm -f "$f"
            rm -rf "${f%.jsonl}" 2>/dev/null  # associated subagent dirs
        done
    fi
done

This reduced my total session storage from 1.5GB to 47MB and eliminated the startup grinding.

Environment

• Claude Code Version: 2.1.x
• Platform: Raspberry Pi 5 (16GB RAM), Linux 6.12.x
• Usage pattern: 5-10 sessions/day across 6-8 projects over ~3 months
• Node.js: v22.x (via nvm)

Impact

• Low-memory systems (Pi, older laptops, cloud VMs): OOM crashes
• All systems: Progressively slower startup times proportional to session accumulation
• User experience: No visibility into the problem until it manifests as crashes or grinding

Suggested Fix

1. Built-in retention policy with sensible defaults (e.g., 30 sessions, 30 days, 100MB max file size)
2. User-configurable limits in settings
3. Lazy/deferred indexing — don't scan all files on startup unless --resume is used
4. Startup warnings when session storage exceeds thresholds

Related Issues

• [BUG] Session files grow unboundedly, causing OOM crash on startup ("Aborted (core dumped)") #20367 — Individual large session files causing OOM (overlapping but different root cause)
• Claude Code crashes with SIGABRT when session JSONL files exceed V8 heap limit #19025 — V8 heap limit exceeded during session parsing
• Claude Code Memory Leak - Process Grows to 120+ GB RAM and Gets OOM Killed #4953 — Process grows to 120GB+ RAM (likely related to session accumulation)