How do I fix the Claude Code 472 GB debug bug? A step-by-step howto

At 11:47 PM on a Tuesday, Claude Code froze mid-response. The status line blinked, then the next request returned an error that mentioned ENOSPC. The MacBook had 1.8 GB free on a 1 TB drive. Earlier that day there had been 95 GB free. Nothing had been downloaded. Nothing had been installed. The only thing that had run was a long Claude Code session with three MCP servers attached. The user opened Activity Monitor, then DaisyDisk, and the picture matched a now-familiar GitHub thread word for word: "I used DaisyDisk to dig into the issue and discovered folders taking up 472GB, both related to Claude CLI." (anthropics/claude-code Issue #18869)

This post is the tactical companion to that story. If you have already lost the disk, or you suspect you are about to, this is the howto.

What exactly is the Claude Code 472 GB debug bug?

The bug, tracked as Claude Code Issue #18869, is not a memory leak or a crash. It is an unbounded-write pattern. Two paths in particular grow forever by default:

1. ~/.claude/debug/ holds verbose Claude Code session logs. One file per session, never garbage-collected until you set a retention policy.
2. ~/Library/Caches/claude-cli-nodejs/<project>/--mcp-logs-<server>/ captures stdout and stderr from every MCP server the CLI spawns. One log stream per MCP server per project, kept indefinitely.

If you use Claude Code for one project a week with no MCP servers, neither path matters. If you use it daily across five projects with three MCP servers each, you are writing fifteen independent log streams in addition to the base debug folder. After four months that is a 472 GB hole in your drive. The pattern is reproducible enough that the Anthropic team shipped cleanupPeriodDays as the documented mitigation.

How do I check if I'm affected?

Before you delete anything, get the receipts. Open Terminal and run:

# Size each suspect path. -h gives human-readable units.
du -sh ~/.claude/debug 2>/dev/null
du -sh ~/Library/Caches/claude-cli-nodejs 2>/dev/null

# Optional: see which projects under MCP logs are the biggest.
du -sh ~/Library/Caches/claude-cli-nodejs/*/ 2>/dev/null | sort -h | tail -10

# Free space on your boot drive for context.
df -h /

The first two commands are the diagnostic. Use this table to classify what you see:

The third command, the per-project breakdown, helps when one project (often the one with the chattiest MCP servers) is responsible for the bulk of the growth. That detail matters when you are choosing between a targeted cleanup and a full sweep.

What is the actual fix?

Three commands plus a one-line settings change. Run them in order.

# Step 1. Confirm the sizes one more time so you know what you reclaimed.
du -sh ~/.claude/debug ~/Library/Caches/claude-cli-nodejs 2>/dev/null

# Step 2. Move the verbose debug folder to Trash. Not rm. Trash.
#         Tagging the folder with a date lets you find it if you need it back.
mv ~/.claude/debug ~/.Trash/claude-debug-$(date +%Y%m%d-%H%M%S)

# Step 3. Move the MCP log cache to Trash the same way.
mv ~/Library/Caches/claude-cli-nodejs \
   ~/.Trash/claude-cli-nodejs-$(date +%Y%m%d-%H%M%S)

# Step 4. Confirm the reclaim landed.
df -h /

That is the deletion side. The two mv commands free everything that was bloating those paths and leave a dated copy in Trash for seven days, in case you find out tomorrow you wanted one of those logs.

Now the prevention side. Open ~/.claude/settings.json in any editor:

# Open the settings file. Create it if it does not exist.
[ -f ~/.claude/settings.json ] || echo '{}' > ~/.claude/settings.json
open -a TextEdit ~/.claude/settings.json

Add the cleanupPeriodDays key. The minimum useful version of the file is:

{
  "cleanupPeriodDays": 4
}

If you already have other keys in there, leave them and add this one. Four days is a sensible default. It keeps enough recent debug output to investigate yesterday's flaky session and not enough to accumulate a hundred gigabytes.

Restart Claude Code so the new setting takes effect on the next session. That is the whole fix.

What is safe to delete and what is not?

This is the part that trips people up when they get aggressive and start rm-ing everything under ~/.claude/. The structure matters.

The two rows marked Yes at the top are the entirety of the 472 GB bug surface. Touching anything else is unrelated to this fix and risks breaking auth, history, or settings. The file-history bug is a separate failure mode in ~/.claude/projects/ that needs a different, more careful approach.

What if the drive is already at zero?

If you cannot open Terminal because the boot drive is wedged, boot into recovery mode and run the same mv commands against the user home from there. APFS reservation usually keeps you above true zero, but the GUI starts misbehaving long before the disk literally fills. Two mv calls into /Users/<you>/.Trash/ free the same space whether you run them from Finder or from the recovery shell.

If macOS already failed an update with the "Your Disk Has < 5GB space remaining" error, run the fix first, then empty Trash, then retry. The installer needs roughly 25 GB of headroom for a point release, and the fix typically returns hundreds of gigabytes.

If you also use Cursor, Codex CLI, or Ollama, you may have a second tool stacking on the same disk pressure. See Cursor pack files disk space and the AI tools 16-month footprint audit once Claude is back under control.

How do I make sure this never happens again?

The single best line of defense is the cleanupPeriodDays setting you already added. Beyond that, build one of these two habits.

Option A: a monthly Terminal check. Add this to a note or a launchd job:

#!/usr/bin/env bash
# Monthly Claude Code disk sanity check.
{
  echo "Claude Code disk audit $(date)"
  du -sh ~/.claude/debug ~/Library/Caches/claude-cli-nodejs 2>/dev/null
  df -h /
} | tee -a ~/Library/Logs/claude-disk-audit.log

Set it for the first of the month. If either folder is over 10 GB, run the fix. If both are under, you are fine for another month.

Option B: let a Mac cleaner watch the paths for you. CleanMyDev's Claude Code scanner sizes both folders, shows the last-modified date, classes each subpath by risk, and surfaces them in the same row as the other AI tool caches on your machine. You do not have to remember the paths, type du, or read GitHub issue trackers. The audit runs in seconds and every action is Move-to-Trash by default, not rm -rf.

Both options work. Option B exists because the human memory layer is the thing that fails. Most developers who get hit by the 472 GB bug knew, in the abstract, that logs accumulate. They just never reached for the audit until the disk forced them to.

Is cleanupPeriodDays enough on its own?

For the debug folder and the MCP logs cache, yes. It is the documented mitigation in Issue #18869 and it caps both. It does not cover the file-history watcher loop in ~/.claude/projects/, which needs a separate playbook, and it does not reach MCP servers that write their own data files outside the Claude cache. Audit each MCP server's data directory once a quarter if you run them heavily.

Final checklist

• Ran du -sh on both paths and recorded the starting size.
• Moved ~/.claude/debug to Trash with a dated suffix.
• Moved ~/Library/Caches/claude-cli-nodejs to Trash with a dated suffix.
• Added "cleanupPeriodDays": 4 to ~/.claude/settings.json.
• Restarted Claude Code so the setting takes effect.
• Confirmed reclaimed space with df -h /.
• Scheduled a monthly audit or installed a cleaner that watches the paths.

If every box is checked, the Claude Code 472 GB debug bug is closed on your machine. The next time it tries to grow, the cap stops it before the disk does.

If you would rather skip the Terminal steps and have a Mac cleaner that already knows every Claude Code path, scanner classifications and all, CleanMyDev does this scan and the recovery for $9.99 lifetime. Move-to-Trash by default. Never sudo. Pre-configured for the two paths called out in Issue #18869, plus the file-history paths from Issue #10107.

Related reading

• Claude Code ate 472 GB of my MacBook: the postmortem
• Cleaning Claude Code disk usage on Mac
• Claude Code file-history bug: where 300 GB went