Bug: Excessive file-history-snapshot logging causes 222 MB session log bloat

Bug Report: Excessive file-history-snapshot Logging Causes Session Log Bloat

Summary

Session log files (.jsonl) in ~/.claude/projects/ can grow to extreme sizes (222 MB observed) due to excessive file-history-snapshot entries being logged at an abnormal rate of ~31 snapshots per second, resulting in performance degradation and wasted disk space.

Environment

• Claude Code Version: 2.0.14
• Platform: macOS (Darwin 25.0.0)
• Affected File: ~/.claude/projects/-Users-edinho-projects-terry/9557baa8-7823-49cb-8780-415e60391940.jsonl
• Session Duration: ~8.65 hours (2025-10-13 23:38:25 → 2025-10-14 08:17:19)

Problem Description

During a long-running session, the file history tracking mechanism logged file-history-snapshot entries at an excessive rate, creating an abnormally large session log file.

Statistics

• File Size: 222 MB (232,519,547 bytes)
• Total Lines: 981,547
• file-history-snapshot entries: 981,140 (99.96% of file)
• Actual conversation entries: 407 (265 assistant + 139 user + 3 system)
• Logging Rate: ~31 snapshots/second continuously for 8.65 hours

Evidence

Snapshot timestamps showing rapid-fire logging:

2025-10-13T23:23:42.689Z
2025-10-13T23:23:42.713Z  ← 24ms apart
2025-10-13T23:23:42.733Z  ← 20ms apart
2025-10-13T23:23:42.752Z  ← 19ms apart
2025-10-13T23:23:42.775Z  ← 23ms apart

Later in the session:

2025-10-14T07:08:58.352Z
2025-10-14T07:08:58.352Z  ← Same millisecond (multiple entries!)
2025-10-14T07:08:58.352Z
2025-10-14T07:08:58.352Z
2025-10-14T07:08:58.352Z

Typical snapshot structure (most are empty):

{
  "type": "file-history-snapshot",
  "messageId": "...",
  "snapshot": {
    "messageId": "...",
    "trackedFileBackups": {},
    "timestamp": "2025-10-13T23:23:42.828Z"
  },
  "isSnapshotUpdate": false
}

Entry type distribution (first 1000 lines):

  908 file-history-snapshot entries
   92 actual conversation entries (user, assistant, system)

Impact

User Impact

• Disk Space: Single session consuming 222 MB vs typical 1-2 MB
• Performance: Large files slow file I/O operations
• Log Management: Difficult to review/debug session history
• User Experience: Confusion about excessive disk usage

System Impact

• Storage bloat in ~/.claude/projects/ directories
• Potential for multiple affected sessions compounding the issue
• Increased backup sizes if session logs are included

Expected Behavior

File history snapshots should be logged:

• On actual file changes/edits
• Periodically (e.g., every few minutes at most)
• Not continuously at 31 snapshots/second

Reference: Other sessions in the same project show normal behavior with 5-32 total snapshots per session.

Actual Behavior

The file history tracking mechanism enters a state where it logs snapshots continuously at millisecond intervals, regardless of whether files are actually being modified.

Reproduction

Unknown - appears to be a race condition or state corruption issue

Potential triggers (speculation):

• Long-running sessions (8+ hours)
• Specific file operations that trigger snapshot loop
• Concurrent file operations
• Large file operations that don't complete cleanly

Comparison with Normal Sessions

Analysis of other session logs in the same project:

| Session | Size | Lines | Snapshots | Snapshot Rate |
|---------|------|-------|-----------|---------------|
| Affected | 222 MB | 981,547 | 981,140 | 31/sec |
| Normal #1 | 1.6 MB | 195 | 5 | Normal |
| Normal #2 | 1.4 MB | 426 | 25 | Normal |
| Normal #3 | 1.3 MB | 423 | 15 | Normal |
| Normal #4 | 900 KB | 263 | 32 | Normal |

Workaround

Delete the affected .jsonl file. This removes the session history but does not affect Claude Code functionality or other sessions.

rm ~/.claude/projects/<project-name>/<session-id>.jsonl

Suggested Fix

1. Rate Limiting: Implement rate limiting for file-history-snapshot logging

• Maximum snapshots per minute/hour
• Debounce snapshot creation to prevent rapid-fire logging

1. Conditional Logging: Only log snapshots when:

• Actual file content changes are detected
• Sufficient time has elapsed since last snapshot (e.g., 30 seconds minimum)
• File tracking state meaningfully changes

1. Circuit Breaker: Detect and halt excessive snapshot logging

• Monitor snapshot creation rate
• Break out of loops creating snapshots too rapidly
• Log warning when abnormal rate detected

1. Size Limits: Implement session log size limits

• Warn when log exceeds reasonable size (e.g., 10 MB)
• Rotate or truncate logs that grow too large
• Provide claude history prune for session logs (similar to #5024 for .claude.json)

1. Diagnostics: Add debug logging to identify:

• What triggers snapshot creation
• Stack traces when rapid snapshot loops occur
• State that causes continuous snapshot logging

Related Issues

This issue is distinct from existing .claude.json bloat issues:

• #5024: History accumulation in .claude.json (config file)
• #6394: .claude.json bloat consolidated feedback (config file)
• #2713: Partial keystrokes in .claude.json (config file)

Key Difference: This affects per-session .jsonl log files in ~/.claude/projects/, not the global ~/.claude.json config file.

Additional Context

• Issue appears isolated to single session (other sessions normal)
• No pattern identified in session content that might trigger bug
• Git repository status: Not a git repository (may be relevant)
• Most snapshots have empty trackedFileBackups: {} objects

Verification Steps

To check if you're affected:

# Find large session logs
find ~/.claude/projects -name "*.jsonl" -size +10M -exec ls -lh {} \;

# Check snapshot counts in a log
grep -c '"type":"file-history-snapshot"' <logfile.jsonl>

# Check total lines
wc -l <logfile.jsonl>

# Calculate snapshot rate (snapshots vs normal entries)

---

Impact Severity: Medium

• Not affecting core functionality
• Isolated occurrences
• Easy workaround (delete file)
• Potential for significant disk waste if widespread

Priority: Should be investigated to prevent recurring issues and understand root cause.