"Background Task Ate 324 GB of Disk Space." That headline comes from engineer Roman Diachenko, who walked over to his Mac one morning and found a .output file that had not existed sixteen minutes earlier sitting on his disk at multi-gigabyte size. The CLI was watching its own writes. Every time it journalled an edit, the journal triggered another edit event, which it then journalled. By the time he caught it, Claude Code's project folder under ~/.claude/projects/ had passed 300 GB on a 1 TB drive. The post-mortem he filed eventually surfaced as anthropics/claude-code Issue #10107, and it is the most concrete example of why your ~/.claude folder can quietly outgrow the rest of your user account in a long weekend.
What is the Claude Code file-history bug, in one paragraph?
Claude Code keeps a per-project memory of edits, prompts, and tool calls under ~/.claude/projects/<hash>/. To make that memory durable, the CLI watches files it has written and records when they change. The bug is that on some macOS file-system event configurations, the CLI's own write of the journal counted as a new file event, which it then journalled again. Each iteration appended to the same .output and history files. With no upper bound on file size and no de-duplication on the watcher input, the loop happily wrote until the disk filled. The most cited reproduction logged a single .output file growing past one gigabyte in sixteen minutes of idle background time.
Why does this matter when my MacBook is "just" full?
Because the bytes look like normal Claude Code state to every macOS tool you would use to find them. They sit under ~/.claude/projects/, which is the same folder that legitimately holds your project memory and todos. About This Mac counts them as User. Finder shows them as ordinary .output files with last-modified dates in the current week. DaisyDisk surfaces them only after you have already used most of your remaining headroom. The first time most engineers learn about this folder is when macOS refuses to install a point release because there are less than 5 GB free, which is exactly the failure mode reported in the related Claude Code 472 GB postmortem.
How big can the Claude Code file-history bug get?
Reported sizes range from "I thought I had plenty of space" to drive-fills. The two best-documented cases are these.
| Case | Source | Size on disk | Time to grow |
|---|---|---|---|
| Diachenko background task | Issue #10107 reproduction | 324 GB in ~/.claude/projects/<hash>/ |
A weekend of idle watcher activity |
| Cascade failure to zero bytes | Issue #24207 | Unbounded growth, disk to 0 bytes free | Days, ending in auth wipe |
| 472 GB MCP variant | Issue #18869 | 472 GB under ~/Library/Caches/claude-cli-nodejs |
Four to five months of heavy use |
| Typical quiet case | Engineer who never opens DaisyDisk | 30 to 80 GB inside one project hash | One to two months |
The pattern is the same in every report: an unbounded write triggered by the CLI's own edits, sitting in a directory the engineer never lists. The size is whatever your free disk was before you noticed.
How do I find the Claude Code file-history bug on my Mac?
Start with du, because the only useful number is the per-project-hash one. The folder names are content hashes, so a single line like du -sh ~/.claude will tell you the total but not which project is leaking. Drop one level deeper.
# Quit any running claude sessions first so files are not held open.
pkill -f "claude" || true
# Top-level number. This is the headline you would see in DaisyDisk.
du -sh ~/.claude
# Per-project breakdown. The runaway folder is usually 100x the others.
du -sh ~/.claude/projects/* 2>/dev/null | sort -h | tail -20
# Confirm by sizing the .output and history files inside that folder.
HASH=replace-with-your-project-hash
ls -lhS ~/.claude/projects/$HASH/ | head -10
If the per-project breakdown shows one hash at 20 GB or above while the rest sit under 200 MB each, you are looking at a file-history loop. If you also see a .output file or a history.jsonl whose size makes no sense for the project ("this is a 12-file Swift app, why is the journal 18 GB"), that is your confirmation.
How do I safely delete the Claude Code file-history bug output?
The rule is the same as for any cleanup on a developer Mac: never delete what you have not sized, and never use rm -rf when Trash is right there. The runaway artefacts inside ~/.claude/projects/<hash>/ are diagnostic write output, but the folder around them also holds the memory Claude Code uses between sessions. Target the bytes, not the folder.
# Use the same HASH variable from the du listing above.
PROJ=~/.claude/projects/$HASH
# 1. Confirm the size one more time before moving anything.
du -sh "$PROJ"
# 2. Move the runaway output and history files to Trash, not rm.
mv "$PROJ"/*.output ~/.Trash/ 2>/dev/null
mv "$PROJ"/history.jsonl ~/.Trash/claude-history-$(date +%Y%m%d).jsonl 2>/dev/null
# 3. Re-size and verify the CLI still launches.
du -sh "$PROJ"
claude --version
If claude --version prints a build string, you did not break your auth, your settings, or your project memory. The .output files are pure diagnostic recursion and the CLI rebuilds whatever it actually needs on the next run. If you would rather scope the deletion to a single project folder and review every file before it moves, CleanMyDev opens ~/.claude/projects/ per hash, sorts by size, and flags any folder that has grown by an unusual delta in the last week. Same move-to-Trash semantics under the hood, no rm -rf, restorable for thirty days if you misclick.
What happens if I delete the whole ~/.claude folder?
You will be signed out of Claude Code, you will lose your per-project memory, you will lose any unsynced todos, and your settings.json will revert to defaults. That is the cascade documented in Issue #24207. The author of that report watched unbounded growth fill the disk to zero bytes and then attempted a recovery rm -rf on ~/.claude to free space, which destroyed his auth at the same time. The recovery is not catastrophic, but it costs a Saturday.
The safer move is two-pass. Scope first to the runaway project hash, then if the rest of ~/.claude still feels large, attack ~/.claude/debug/ and ~/Library/Caches/claude-cli-nodejs/ per the Claude Code disk usage cleanup playbook. Never the whole ~/.claude in one shot.
How do I stop the Claude Code file-history bug from coming back?
Two checkboxes. Update the CLI, then cap its writes with the setting Anthropic added specifically for this class of bug.
// ~/.claude/settings.json
{
"cleanupPeriodDays": 4
}
cleanupPeriodDays tells Claude Code to roll off aged history and diagnostic data older than the number of days you specify. Four is a comfortable default for daily users. Two is aggressive, seven is forgiving, thirty is "I want a long tail of recoverable history." Any bounded number is better than the default, which is unbounded.
The patched CLI also closes the most aggressive recursion in the watcher, but the configuration line is the seatbelt. Set it once. Treat it the way you treat set -e in a shell script: not because the script is broken, because the consequences of one bad iteration are too expensive to skip.
How does this compare to other AI coding tool disk bugs?
Same shape, different paths. Most modern AI coding tools default-on a diagnostic write and default-off any cap on it.
| Tool | Runaway path | Documented worst case | Cap mechanism |
|---|---|---|---|
| Claude Code (file history) | ~/.claude/projects/<hash>/*.output |
324 GB in one weekend | cleanupPeriodDays plus CLI patch |
| Claude Code (MCP logs) | ~/Library/Caches/claude-cli-nodejs/--mcp-logs-* |
472 GB in four months | Manual cache clear |
| Cursor | Application Support/Cursor/User/workspaceStorage/*.pack |
70 GB across 300+ packs | Recent Cursor cap |
| Codex CLI | ~/.codex/sessions/ and worktrees |
30 GB over weeks | Manual prune |
| Cline | VS Code globalStorage checkpoints | 40 GB per repo | Per-checkpoint delete |
If you run more than one of these, expect the total to land in the hundreds of GB by month six. The Cursor side is covered in Cursor .pack files are eating disk space, and the rest of the cluster keeps showing up in audit posts because nobody else is treating these caches as part of the developer Mac storage story.
Why use CleanMyDev for the Claude Code file-history bug?
You can solve one instance of this bug with three du calls and an mv. You cannot solve every instance, because the bug landed in a folder you do not list, with files that look ordinary, sized in a unit you would not notice until macOS blocks an update. CleanMyDev scans ~/.claude/projects/ per hash, sorts by size, surfaces anything that grew faster than its peers, and labels each file as state or diagnostic. Move to Trash by default, no rm -rf ever, restorable. The same scan covers Cursor, Codex CLI, Cline, Ollama, and Hugging Face, so the next bug of this shape does not get four months of runway.
If you would rather not be the next entry in the GitHub issue tracker, CleanMyDev is $9.99 once, ships with the Claude Code scanner preconfigured, and treats ~/.claude/projects/ as a first-class target.