How do I clean up Claude Code disk usage on my Mac?

"I used DaisyDisk to dig into the issue and discovered folders taking up 472GB, both related to Claude CLI." That sentence comes from anthropics/claude-code Issue #18869, filed by an M1 Max owner who could not install a macOS point release because his 1 TB drive had less than 5 GB free. The 472 GB was not application code. It was Claude Code's own diagnostic output, accumulated quietly across four months of heavy CLI use. If your ~/.claude folder feels suspiciously large, you are looking at the same mechanic on a smaller scale.

What does Claude Code actually write to disk on a Mac?

Claude Code is one CLI binary with two on-disk footprints. The claude command keeps state under ~/.claude. The Node MCP harness writes per-project diagnostic streams to ~/Library/Caches/claude-cli-nodejs/. The first directory is small and important. The second is the one that grows without an upper bound if you do not configure it. Knowing which file belongs to which path is the difference between freeing 80 GB in one minute and breaking your authentication for a week.

Here is the layout, sized after a typical six months of heavy daily use on a developer Mac.

Almost all of the visible Claude Code disk usage pressure on a developer Mac comes from the bottom two rows.

How do you measure Claude Code disk usage before you touch anything?

The rule is the same as for any cleanup: never delete what you have not sized. Three du calls give you a complete picture.

# Top-level claude directory.
du -sh ~/.claude

# Per-subfolder breakdown, sorted, to see which folder is winning.
du -sh ~/.claude/* 2>/dev/null | sort -h

# The MCP cache that is usually 10x larger than ~/.claude itself.
du -sh ~/Library/Caches/claude-cli-nodejs

# Drill into per-project MCP logs to find the worst offender.
du -sh ~/Library/Caches/claude-cli-nodejs/*/--mcp-logs-* 2>/dev/null | sort -h | tail -20

If the bottom of that last list shows anything over 5 GB inside a single --mcp-logs-* folder, that one subfolder is your bleed. If the sum of ~/Library/Caches/claude-cli-nodejs is over 50 GB, you are running the same shape of bug documented in the Claude Code 472 GB postmortem.

Which Claude Code paths are safe to delete and which are not?

Two classes of files live under the Claude Code footprint. State and diagnostics.

State is what makes Claude Code useful between sessions: your auth tokens, your todos, your project memory, your settings file. Those live in ~/.claude/projects/, ~/.claude/todos/, ~/.claude/.credentials.json, and ~/.claude/settings.json. Together they typically total under 250 MB even after a year. Do not touch them.

Diagnostics is what makes a bug report possible: debug dumps, history JSONL, MCP stdout captures. Those live in ~/.claude/debug/, optionally ~/.claude/history.jsonl, and ~/Library/Caches/claude-cli-nodejs/. These can total anywhere from 8 GB on a light user to the well-documented 472 GB on a worst case.

The wrong fix that wipes auth is rm -rf ~/.claude. That is exactly the cascade-failure case documented in anthropics/claude-code Issue #24207, where unbounded growth fills the disk and a hand-rolled cleanup destroys settings and auth at zero bytes free. You do not want to be on either side of that line.

The right fix is surgical, scoped to the two diagnostic paths.

How do you clean Claude Code disk usage step by step?

This is the safe sequence. Four steps, none of them destructive without a Trash safety net.

# Step 1. Quit any running claude sessions so files are not held open.
pkill -f "claude" || true

# Step 2. Move the debug folder to Trash. Recreated on next run.
mv ~/.claude/debug ~/.Trash/claude-debug-$(date +%Y%m%d) 2>/dev/null

# Step 3. Move the MCP log cache to Trash. Also recreated on next run.
mv ~/Library/Caches/claude-cli-nodejs ~/.Trash/claude-cli-nodejs-$(date +%Y%m%d) 2>/dev/null

# Step 4. Verify Claude still works.
claude --version

If claude --version prints a version string, you did not break anything. Your auth is intact, your projects are intact, your todos are intact. The two diagnostic folders are recreated empty on the next claude invocation.

If you would rather see every file before it moves, CleanMyDev opens both paths in one scan and lets you eyeball each subfolder before clicking through. Same mv to Trash under the hood, no rm -rf ever, restorable for the next 30 days if you misclicked.

How do you cap Claude Code disk usage so this does not happen again?

Anthropic shipped cleanupPeriodDays specifically because of this class of bug. It is not on by default. Add it once and forget it.

// ~/.claude/settings.json
{
  "cleanupPeriodDays": 4
}

That tells Claude to roll off conversation transcripts and aged diagnostic data older than four days. Pick whatever value matches your tolerance. Two days is aggressive, seven is comfortable, thirty is forgiving and still bounded. The point is bounded.

One caveat: cleanupPeriodDays does not always reach into the MCP log cache. Set it for the ~/.claude side, then also schedule a monthly check of ~/Library/Caches/claude-cli-nodejs/. The pattern shipped in brtkwr's "Using Claude to free 200GB from a full disk" writeup found this exact MCP path among the heaviest cleanups on a 487 GB used disk. Quote from that author after the initial pass: "After the initial Docker/cache cleanup freed 150GB, going back and asking 'what else?' found another 75GB." Claude Code's MCP cache is reliably in that second pass.

What if you already ran rm -rf ~/.claude and lost auth?

If you nuked the whole folder and claude login now shows you signed out, the recovery is annoying but not destructive.

1. You do not need to reinstall the CLI. Run claude login again to refresh tokens.
2. Project memory under ~/.claude/projects/ is gone if you did not back it up.
3. Conversation history under ~/.claude/history.jsonl is gone.
4. Settings need to be recreated. Re-add "cleanupPeriodDays": 4 immediately so the same bloat does not return.

This is the cost of nuking the whole folder instead of the two diagnostic subpaths. It is recoverable, but it is the kind of recoverable that costs you a Saturday. The next time, target debug and the MCP cache only.

How does Claude Code disk usage compare to other AI coding tools?

This is a category-wide pattern. Different tool, same shape: a default-on, default-unbounded diagnostic write.

If you run more than one of these in a real codebase, expect cumulative bloat in the hundreds of GB by month six. The mechanics are detailed for each tool in Cursor .pack files are eating disk space and the rest of the AI tools cluster.

Why use CleanMyDev for Claude Code cleanup instead of a shell script?

You do not need an app to run mv ~/.claude/debug ~/.Trash/. You do need an app the moment you forget to run it for four months. CleanMyDev sizes every Claude Code subfolder on demand, flags the diagnostic ones in green and the state-bearing ones in red, and uses Move to Trash by default so a misclick is recoverable. It also knows the equivalent paths for Cursor, Codex CLI, Cline, Ollama, and Hugging Face, so one scan covers every AI tool on your developer Mac rather than one CLI at a time.

The pitch in one line: skeptical-dev cleaner that shows the receipts before it deletes anything. No subscription, no scareware, no rm -rf. If you want to stop manually grepping du output every quarter, CleanMyDev is $9.99 once and ships with the Claude Code scanner preconfigured.

Related reading

• How did Claude Code use 472 GB of my MacBook? A postmortem
• Claude Code file-history bug: 300 GB explained
• Cursor .pack files are eating disk space: a safe cleanup