[BUG] Claude code is killed by OOM killer due to subprocess issue

I've also been experiencing this issue. Seemingly randomly claude will be killed by the OOM killer. I've had claude investigate and here's what it's said: "Claude process grows from ~2.5GB to 24-26GB RSS over long sessions before getting OOM killed. On a 31GB RAM + 2GB swap system, dmesg shows repeated kills at anon-rss:24-26GB. Memory appears to accumulate during extended conversations with many tool calls/subagents."

However, I can say that the sessions aren't necessarily long, because my most recent bout with this issue was only after 20 minutes of usage doing some git archaeology and light debugging.

Claude Code CLI Memory Leak - Complete Solution

TL;DR - Working Solution

Problem: Claude Code crashes with FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

Root Cause: Accumulated cache in ~/.claude/ directories (especially shell-snapshots/ at 1.5GB+)

What DOESN'T Work:

• ❌ Increasing heap limits via NODE_OPTIONS or alias modifications
• ❌ Global .claudeignore files
• ❌ Weekly cron cleanup (too infrequent)
• ❌ Changing agent architecture without cache cleanup

What DOES Work:

• ✅ Aggressive cache cleanup script (JSON file cleanup) - TESTED FOR SEVERAL DAYS, CONFIRMED WORKING
• ✅ Monitor cache size with du -sh ~/.claude/ before/after sessions
• ✅ Nuclear cleanup before restarting after any OOM crash

Quick Fix:

# Run this immediately after OOM crash or when cache exceeds 500MB:
rm -rf ~/.claude/{projects,todos,file-history,shell-snapshots,debug}/* ~/.claude/history.jsonl ~/.cache/claude-cli-nodejs/ /tmp/claude-*

See [Prevention](#prevention) section for automated cleanup script and full solution.

---

Root Cause

The Claude Code CLI accumulated 1.7GB of cached data across shell-snapshots (1.5GB), conversation history JSONLs (77MB), todo stubs (11MB), and file-history (8MB), which the V8 JavaScript engine attempted to load or parse on startup and during operations, causing garbage collection to fail when heap exceeded 24GB and triggering an "Ineffective mark-compacts near heap limit" fatal error.

Trigger Patterns:

• Primary Trigger: Subagent/sub-subagent usage accelerates cache accumulation, triggering OOM crashes faster
• Secondary Trigger: Random occurrences during normal operations, but less frequent
• Note: Cleanup solution (JSON file cleanup) resolves OOM crashes regardless of agent architecture used

What We Missed

The shell-snapshots directory silently grew to 1.5GB without any visible warning or monitoring. Each shell environment capture stored approximately 244KB, and over extended usage, 28+ snapshots accumulated. The initial investigation focused on conversation JSONL files (the commonly reported culprit in community discussions) and missed checking ~/.claude/shell-snapshots/ entirely during the first diagnostic pass. The early signal was the V8 garbage collection metrics in the crash log showing mu = 0.276 (mutation rate), indicating the engine spent 72% of its time attempting garbage collection rather than executing work—a clear indicator of memory pressure from large cached objects rather than runtime agent spawning.

Prevention

Immediate Actions (Under 30 Minutes)

1. Create a cleanup script at ~/.local/bin/claude-cleanup.sh:

#!/bin/bash
echo "=== Claude Code Cache Cleanup ==="
rm -rf ~/.claude/projects/
rm -rf ~/.claude/todos/
rm -rf ~/.claude/file-history/*
rm -rf ~/.claude/shell-snapshots/*
rm -rf ~/.claude/debug/*
rm -rf ~/.cache/claude-cli-nodejs/
rm -f ~/.claude/history.jsonl
rm -rf /tmp/claude-*
echo "✓ Cleanup complete"
du -sh ~/.claude/

1. Add weekly cron job:

crontab -e
# Add line:
0 9 * * 1 ~/.local/bin/claude-cleanup.sh >> ~/.claude/cleanup.log 2>&1

1. Create monitoring alias in ~/.bashrc or ~/.zshrc:

alias claude-size='echo "=== Claude Cache Sizes ===" && du -sh ~/.claude/ ~/.claude/shell-snapshots/ ~/.claude/projects/ ~/.claude/file-history/ 2>/dev/null'

1. Set heap limit to prevent runaway memory (add to shell profile):

export NODE_OPTIONS="--max-old-space-size=8192"

Session Hygiene Rules

• Run claude-size before starting intensive work sessions
• If ~/.claude/ exceeds 500MB, run cleanup before continuing
• RECOMMENDED: Run cleanup script after sessions using subagents (accelerates cache growth)
• Never /resume sessions older than 24 hours without checking cache sizes
• Exit Claude Code completely and run cleanup script before restarting if OOM occurs
• Consider cleanup after extended sessions (>30 minutes) with heavy parallel operations

Warning Thresholds

| Directory | Warning | Critical | Action |
|-----------|---------|----------|--------|
| ~/.claude/ total | >500MB | >1GB | Run cleanup script |
| shell-snapshots/ | >100MB | >500MB | Clear immediately |
| projects/ | >50MB | >200MB | Clear conversation history |
| Single JSONL file | >1MB | >5MB | Session too long, restart |

Quick Reference

Location: ~/.claude/ (primary), ~/.cache/claude-cli-nodejs/ (secondary)

Symptom:

• CLI freezes on startup
• System RAM climbs to 40GB+ while idle
• Error: FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory
• Error: v8::internal::Heap::CollectGarbage allocation failure
• GC log shows mu < 0.3 (mutation rate below 30%)
• More frequent: Crashes during or after sessions with subagent/sub-subagent usage (accelerates cache growth)
• Can occur randomly during normal operations (less frequent)

Search:

# Check total cache size
du -sh ~/.claude/

# Find largest cache directories
du -sh ~/.claude/*/ 2>/dev/null | sort -h

# Find all JSONL files with sizes
fd -e jsonl ~/.claude -x ls -lh {} 2>/dev/null | sort -k5 -h

# Check shell snapshots specifically (hidden culprit)
du -sh ~/.claude/shell-snapshots/

# Nuclear cleanup (safe - only removes cache, not config)
rm -rf ~/.claude/{projects,todos,file-history,shell-snapshots,debug}/* ~/.claude/history.jsonl ~/.cache/claude-cli-nodejs/ /tmp/claude-*

Next steps:

1. Run the cleanup script immediately after any OOM crash before restarting Claude Code
2. RECOMMENDED: Run cleanup after sessions using subagents (accelerates cache growth)
3. Add claude-size check to your pre-work routine when opening projects with heavy Claude Code usage
4. Document cache locations in project CLAUDE.md files so team members know the maintenance requirements
5. Consider filing a GitHub issue at anthropics/claude-code requesting:

• Automatic cache rotation or size limits for shell-snapshots directory
• Built-in memory pressure detection and cleanup
• Warnings when cache directories exceed safe thresholds

1. Monitor the Claude Code GitHub issues for memory-related discussions—issues #4953 and #5388 reference similar heap exhaustion patterns

---

Technical Details

Cache Directory Purposes

| Directory | Purpose | Regenerates? |
|-----------|---------|--------------|
| projects/ | Conversation history per project | Yes, on new session |
| todos/ | Task tracking state | Yes, on new tasks |
| file-history/ | Edit undo/redo snapshots | Yes, on file edits |
| shell-snapshots/ | Shell environment captures | Yes, on shell commands |
| debug/ | Debug logging output | Yes, on debug operations |
| local/ | CLI binaries (DO NOT DELETE) | No - breaks CLI |
| plugins/ | Skill definitions (DO NOT DELETE) | No - breaks skills |

Memory Architecture

Claude Code runs on Node.js with V8 engine. Default heap limit scales with available RAM but can exceed safe thresholds. The CLI loads conversation history and cached state on startup, making accumulated cache a startup-time memory bomb rather than a runtime issue. This explains why OOM can occur even when idle—the damage happens during initialization.

Differentiation: Runtime vs Startup OOM

| Characteristic | Startup OOM | Runtime OOM | Agent-Accelerated OOM |
|----------------|-------------|-------------|----------------------|
| When | Immediately on claude command | During active work | During/after agent spawning |
| Cause | Large cached files being parsed | Too many parallel agents | Rapid cache accumulation |
| Fix | Delete cache files | Limit agent count, /compact | Cache cleanup |
| GC Pattern | Aggressive from start | Gradual degradation | Faster accumulation |
| Session age | Irrelevant | Longer = worse | Can happen faster |
| Memory growth | Linear (cache size) | Linear (agent count) | Accelerated (agent usage) |

Compounding effect: Subagent/sub-subagent usage creates cache files faster, which can cause startup OOM on next launch if not cleaned. After cleanup, OOM crashes resolve regardless of agent architecture used.

Related GitHub Issues

This solution addresses memory issues reported in:

• anthropics/claude-code#4953 - Heap exhaustion patterns
• anthropics/claude-code#5388 - Similar OOM crashes

Recommended upstream improvements:

1. Built-in cache rotation with configurable size limits
2. Automatic cleanup of shell-snapshots older than 7 days
3. Warning when ~/.claude/ exceeds 500MB
4. Memory pressure detection with graceful degradation
5. Documentation of cache directory purposes and cleanup procedures

---

What Didn't Work

Important: The following solutions from /home/fivefingerdisco/.claude/docs/MEMORY_TROUBLESHOOTING.md were attempted but failed to resolve the OOM crashes. Do not rely on these approaches.

Failed Solution 1: Hardcoded Heap Limits in Alias (December 2025)

Attempted Fix:

# This DID NOT WORK:
alias claude='NODE_OPTIONS="--max-old-space-size=8192" /home/fivefingerdisco/.claude/local/claude'

# Increasing to 24GB also DID NOT WORK:
alias claude='rm -rf ~/.claude/debug/* 2>/dev/null; NODE_OPTIONS="--max-old-space-size=24576" /home/fivefingerdisco/.claude/local/claude'

Why it failed:

• The inline NODE_OPTIONS in the alias overrides any export NODE_OPTIONS in the shell
• Setting heap limits doesn't address the root cause (accumulated cache files)
• Crashes still occurred at exactly 8GB or 24GB thresholds

Failed Solution 2: Global .claudeignore (December 2025)

Attempted Fix:

# ~/.claudeignore
node_modules/
.next/
.git/
coverage/

Why it failed:

• .claudeignore only affects which files Claude reads during sessions
• Does NOT prevent cache accumulation in ~/.claude/ directories
• Does NOT impact shell-snapshots or conversation history growth
• Crashes continued regardless of .claudeignore presence

Failed Solution 3: Weekly Cron Cleanup (December 2025)

Attempted Fix:

# Cron: 0 0 * * 0 ~/.local/bin/claude-cleanup.sh
#!/bin/bash
rm -rf ~/.claude/debug/
rm -rf ~/.claude/shell-snapshots/
find ~/.claude/projects -name "*.jsonl" -mtime +30 -delete

Why it failed:

• Weekly cleanup too infrequent for active Claude Code usage
• Cache can grow to critical levels within 24-48 hours with heavy usage
• OOM crashes occurred between cron runs

Failed Solution 4: Agent Architecture Changes Without Cleanup (December 2025)

Attempted Fix:
Changed from 3-tier nested architecture to 2-tier flat architecture:

# OLD: Main → Coordinator → [Exec1, Exec2, Exec3]
# NEW: Main → Subagent1, Subagent2, Subagent3 (flat)

Why it failed:

• Reduced agent nesting may have helped marginally with cache accumulation rate
• Cache accumulation still occurred regardless of agent architecture
• Crashes persisted without regular cache cleanup
• The architectural change addressed a potential accelerator, not root cause

Reference: See /home/fivefingerdisco/.claude/docs/MEMORY_TROUBLESHOOTING.md for complete details of failed attempts.

---

The Working Solution

The only approach that actually works is aggressive cache management combined with session hygiene.

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

Still present

Not sure if related but having similar similar issues in Linux. Have to manually kill sessions to interact with the system

issue is still occurring in version 2.1.19

Agent Teams caused kernel panic (2x reboots) on 7.6GB server with no swap

Environment

• Instance: AWS EC2 t3.large (2 vCPU / 7.6GB RAM / no swap)
• OS: Ubuntu 24.04.3 LTS
• Claude Code: Latest version

What happened

Asked Claude Code to spawn an Agent Team with 4 subagents to test Playwright across multiple remote servers. Each subagent spawned its own set of MCP servers (Playwright, Slack, context7, sequential-thinking).

Result: Server kernel-panicked twice in a row.

Memory timeline from sar -r

| Time | Free (MB) | %Used | Note |
|------|-----------|-------|------|
| 14:30 | 3,091 | 11.3% | Normal |
| 14:40 | 3,006 | 12.3% | Team spawning |
| 14:50 | 1,581 | 34.8% | Rapidly increasing |
| ~14:55 | 0 | 100% | Kernel panic → reboot |
| 15:03 | LINUX RESTART | | 1st reboot |
| 15:07 | LINUX RESTART | | 2nd reboot (3 min after 1st!) |

~1.4GB consumed in just 10 minutes. The 2nd crash happened because the session auto-restored after boot and the processes tried to resume.

Memory breakdown (single Claude Code session)

From ps aux after recovery:

| Process | RSS |
|---------|-----|
| intelephense (LSP) | 1.7 GB |
| claude (main) | 546 MB |
| playwright-mcp | 103 MB |
| context7-mcp | 84 MB |
| sequential-thinking | 68 MB |
| slack-mcp | 53 MB |
| Total per session | ~2.5-3 GB |

With 4 subagents, each spawning their own MCP stack: ~12-15 GB required on a 7.6 GB machine with no swap.

Suggestion

Agent Teams (and subagent spawning in general) should check available system memory before launching. Even a simple free -m check with a warning/limit would prevent this class of crash. Currently there's zero resource checking — it just spawns everything and hopes for the best.

Workaround

Added 20GB swap. Now it survives but gets sluggish when swapping.

sudo fallocate -l 20G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Ok so it's not just me. Yeah I periodically get claude being killed by OOM killer and I'm not even a heavy user. I thought I was going crazy. Hopefully they can fix this sooner than later. 2.1.68 (Claude Code) running on Ubuntu 24.04 Gnome workstation.

2026-03-04T16:29:38.448350-08:00 badhorse kernel: Out of memory: Killed process 496994 (claude) total-vm:74808816kB, anon-rss:14477196kB, file-rss:3200kB, shmem-rss:0kB, UID:1000 pgtables:70472kB oom_score_adj:200

I hit this regularly on my Debian VM:

$ uname -a
Linux claude 6.12.74+deb13+1-arm64 #1 SMP Debian 6.12.74-2 (2026-03-08) aarch64 GNU/Linux
$ claude --version
2.1.87 (Claude Code)

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.