[BUG] Claude Code hangs when accessing large session files (>50MB)

Summary

Claude Code becomes completely unresponsive (90% RAM usage, infinite "Ruminating...") when attempting to access or grep large .jsonl session transcript files. A 102MB session file caused complete system freeze requiring force-kill.

Environment

• OS: WSL2 Ubuntu 24.04 on Windows 11
• Claude Code Version: (current as of 2026-01-26)
• Symptom: Infinite "Ruminating..." with high memory usage

Reproduction Steps

1. Run Claude Code session continuously for 3+ days (laptop in sleep mode, no shutdown/restart)
2. Session transcript file grows to 100MB+ (8,366 lines in this case)
3. Execute command that accesses old session (e.g., grep -i "pattern" ~/.claude/projects/[project-name]/[session-id]*.jsonl)
4. Claude Code hangs indefinitely at "Running... Ruminating..."
5. WSL memory usage climbs to 90%, entire system becomes unresponsive

Evidence

Session File That Caused Hang

-rw------- 1 user user 102M Jan 26 09:11 68a8f26e-b699-4fc1-8cf9-a54c67142511.jsonl
Lines: 8,366
Created: 2026-01-20 09:55 UTC
Last activity: 2026-01-23 23:31 UTC

Command That Hung

Bash(grep -i "F") ~/.claude/projects/[project-name]/e66cefac*.jsonl
                  ~/.claude/projects/[project-name]/d4b0538f*.jsonl
                  ~/.claude/projects/[project-name]/68a8f26e*.jsonl)

Screenshot Evidence

See attached screenshot showing:

• Command stuck at "Running..."
• Status: "Ruminating... (Esc to interrupt • 47s • ↓ 27 tokens)"
• Previous successful grep on smaller sessions (e66cefac: 2.4MB returned 3937 lines)
• Hang occurred when reaching 102MB session file

Additional Large Sessions Found

102M  68a8f26e-b699-4fc1-8cf9-a54c67142511.jsonl  (THE KILLER)
6.7M  505efcc6-69d6-4d56-bd3e-7f4ca02f1716.jsonl  (risky)
5.2M  0947dde8-ba89-4f47-839a-0ddc23560d26.jsonl  (borderline)

Impact

• Critical: Requires force-kill of Claude Code process
• Data Loss Risk: Lost work if current session not saved
• System Impact: 90% RAM usage affects entire WSL/Windows system
• User Experience: Cannot access old session history without triggering hang
• Workflow Disruption: Long-running sessions (common in continuous dev environments) become time bombs

Root Cause Analysis

Sessions running continuously across multi-day periods (e.g., laptop sleep Friday → wake Monday) accumulate massive transcript files. Claude Code appears to:

1. Load entire session .jsonl file into memory when accessed
2. Lack size-based safeguards or streaming reads
3. Not warn users about growing session sizes
4. Attempt to process 100MB+ text files synchronously, blocking UI

Workaround Applied

Moved dangerous sessions (>5MB) to archive directory outside Claude Code's project scan path:

mkdir ~/archive-dangerous-sessions-2026-01-26
mv [large-sessions] ~/archive-dangerous-sessions-2026-01-26/

Feature Requests

1. Proactive Session Size Monitoring

• Monitor active session size in real-time
• Display session size in UI (e.g., status bar)
• Warn user at thresholds:
• 20MB: "Session size large, consider starting new session"
• 40MB: "Session size critical, recommend closing and continuing in new session"
• 50MB+: Auto-suggest session rotation

2. Graceful Large File Handling

• Don't load entire .jsonl into memory for operations
• Use streaming/chunked reads for grep/search
• Implement size limits before loading
• Show progress indicator for large file operations

3. Automatic Session Management

• Option to auto-rotate sessions at configurable size (default: 25MB)
• "Continue in new session" feature that:
• Saves current session
• Starts fresh session
• Maintains context continuity
• Links related sessions

4. Session Archival & Export

• Built-in command to archive old sessions
• Export sessions to readable format (markdown, HTML)
• Compress inactive sessions
• Cleanup tool for sessions older than X days

5. Better Error Handling

• Detect when operation is taking too long (>30s)
• Offer to cancel operation
• Show "Large file warning" before processing
• Don't let UI become completely unresponsive

Technical Suggestions

1. Implement lazy loading for .jsonl files
2. Add size checks before file operations
3. Use memory-mapped files for large sessions
4. Consider SQLite for session storage instead of JSON lines
5. Implement session chunking/pagination

Expected Behavior

• Claude Code should never hang, regardless of session file size
• Large files should be handled gracefully with progress indicators
• Users should receive proactive warnings before sessions become problematic
• System should remain responsive even during large file operations

Actual Behavior

• Claude Code hangs indefinitely
• No warning about session size
• No way to recover without force-kill
• Lost access to historical session data

Additional Context

This issue particularly affects users with:

• Continuous development workflows (laptop sleep vs shutdown)
• Long-running debugging sessions
• WSL2 environments (common for Claude Code + Windows users)
• Limited RAM (the 102MB session consumed 90% of available memory)

Related Issues

(Search for related issues about: memory usage, hanging, large files, session management)

---

Note: This is a critical reliability issue that makes Claude Code unusable for long-running sessions. The lack of proactive monitoring means users discover the problem only when Claude Code hangs, not before.