Bug Report: File-history tracking causes catastrophic disk space exhaustion (300GB)

⚠️ Severity: CRITICAL

This bug caused 300GB of disk space consumption before user intervention.

Summary

Claude Code's file-history feature tracks its own internal state files, leading to catastrophic disk space exhaustion when state updates occur rapidly. In this case, it consumed 300GB before the user noticed and intervened.

Reproduction

1. Have a long-running Claude Code session that gets stuck in a loop
2. File-history tracks state file containing cachedChangelog field (~36MB per snapshot)
3. Each state update creates a new 36MB snapshot
4. Result: Exponential disk usage - peaked at 300GB before intervention

Timeline of Disk Usage

• Initial detection: 3.5GB (with auto-cleanup running)
• After killing runaway process: 682MB
• User reports peak usage: 300GB before they caught it

Root Causes

1. File-history tracks internal state (Critical Bug)

File-history should never track files in ~/.claude/ directory, especially not its own state files. This creates a feedback loop where:

• State updates trigger file-history snapshots
• Snapshots consume resources
• More state updates occur
• Cycle repeats exponentially

2. Bloated state file (Design Issue)

The state file contains cachedChangelog field with entire release notes history embedded as text (~36MB). This is stored in file-history snapshots like:

{
  "cachedChangelog": "# Changelog\n\n## 2.0.22\n...[continues for 36MB]..."
}

3. Runaway process (Operational Issue)

Process PID 31698 was stuck in loop, running at 101.7% CPU for 118+ minutes, constantly updating state.

Evidence

• Session: 41e1dc5d-105d-499d-b0d0-44a41dcacf6a
• File tracked: 57f686867b03e3b5 (versions reached v6638+)
• Process: PID 31698 running at 101.7% CPU for 118 minutes
• Peak disk usage: 300GB (user reported)
• Final disk usage after cleanup: 682MB (with auto-cleanup running)
• Each snapshot: ~36MB
• Estimated total versions created: ~8,300 (300GB ÷ 36MB)

Impact

• Critical disk space exhaustion - can fill entire drives
• System instability - low disk space causes OS-wide issues
• Data loss risk - users may lose work if disk fills completely
• Silent failure - no warnings until disk is nearly full

Recommendations

Immediate Fixes (Required)

1. Exclude ~/.claude/** from file-history entirely

   • Add ignore patterns for all internal state
   • Never track file-history's own directory

2. Add emergency circuit breakers:

   • Stop file-history if single file exceeds 100 versions in 10 minutes
   • Alert user if file-history folder exceeds 5GB
   • Auto-disable file-history if disk usage is critical

Design Improvements (Recommended)

3. Remove cached changelog from state - fetch on-demand from API/web
4. Reduce state file size - state should be KB not MB
5. Add file-history health monitoring - detect runaway scenarios
6. Version retention limits - max N versions per file, with aggressive pruning

Documentation (Nice-to-have)

7. Document file-history behavior and disk usage expectations
8. Add troubleshooting guide for disk space issues

System Info

• macOS Darwin 25.1.0
• Claude Code version: Latest (cached changelog through v2.0.22)
• Session file size: 52MB with 7925 lines of conversation history
• File-history location: ~/.claude/file-history/

Related Issues

This may be related to other reports of high disk usage or performance degradation in long-running sessions.