Description

@bcherny @wolffiex Claude Code has no disk space management. The ~/.claude directory grows unbounded, there is no monitoring, no cleanup mechanism, and no user warnings. When the disk fills up, Claude Code enters an unrecoverable cascade failure that destroys user settings and sessions.

Environment

• OS: Windows 10 (MSYS2/Git Bash)
• Claude Code: 2.1.34 (first observed) → 2.1.37 (still present)
• Disk: 293 GB, filled to 0 bytes free by Claude Code's own data

~/.claude disk usage breakdown

~/.claude/projects/      2,707 MB  — session transcripts (unbounded growth)
~/.claude/debug/           734 MB  — debug logs (never cleaned)
~/.claude/file-history/    188 MB  — file snapshots (see #10107: 300 GB for one user)
~/.claude/history.jsonl      6 MB  — command history
~/.claude/plugins/           5 MB
────────────────────────────
TOTAL:                   3,640 MB

Top projects by transcript size:

D--projects-gogpu-gogpu      1,114 MB  (single project!)
D--projects-grpmsoft-grpm      688 MB
D--projects-freicon            328 MB
D--projects-coregx-coregex     273 MB

This is on top of the .node native addon leak (#23095, ~20 GB/week) and claude-*-cwd temp file leak (#8856, thousands of files).

The cascade failure (critical)

When the disk reaches 0 bytes free, Claude Code enters a destructive, unrecoverable state:

1. Write failure — Claude Code cannot write .claude.json (project settings)
2. Corruption — the failed write produces a zero-length file
3. Invalid config — Claude Code reads the empty file, treats it as invalid JSON
4. Settings lost — Claude Code creates a new default config, overwriting all project settings (allowed tools, agent configurations, custom permissions)
5. Authentication lost — OAuth/API tokens are also corrupted or wiped, requiring the user to re-authenticate
6. Agents die — all running agents/sessions stop and cannot recover even after freeing disk space
7. Manual recovery required — user must:
   • Kill all Claude Code processes
   • Free disk space manually (with no guidance on what to clean)
   • Re-authenticate with Anthropic (login again)
   • Restore .claude.json from backup (if one exists)
   • Restart all sessions (losing all conversation context)
   • Re-configure agent settings that weren't in the backup

There is no warning before this happens. No graceful degradation. No recovery path.

What's missing

1. Disk space monitoring (critical)

Claude Code should check available disk space and warn the user in the session UI before it's too late:

⚠️ Warning: Only 2 GB free on C: — Claude Code data is using 3.6 GB in ~/.claude
   Run `claude clean` to free space, or see https://docs.anthropic.com/...

2. Atomic writes for config files (critical)

.claude.json should use write-to-temp-then-rename pattern to prevent corruption:

write → .claude.json.tmp
fsync → .claude.json.tmp
rename → .claude.json.tmp → .claude.json

This is standard practice for any application that persists configuration.

3. claude clean command (enhancement, requested in #11646)

claude clean              # Safe cleanup: old debug logs, stale transcripts, temp files
claude clean --aggressive # Also clean file-history, old project caches
claude clean --dry-run    # Show what would be cleaned

4. Data lifecycle policies (enhancement)

• debug logs: auto-delete after 7 days
• session transcripts: compress after 30 days, delete after 90 days
• file-history: cap at 500 MB per project, LRU eviction
• claude-*-cwd temp files: clean on session exit (still leaking per Memory leak: Missing cleanup for /tmp/claude-*-cwd working directory tracking files #8856)

Related issues

All of these share the same root cause: Claude Code has no resource lifecycle management. Files are created, never cleaned, and when the inevitable happens (disk full), there is no graceful handling.

Workaround

PowerShell cleanup script (should not be the user's responsibility):

# Clean debug logs older than 7 days
Get-ChildItem "$env:USERPROFILE\.claude\debug" -Recurse -Force |
    Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-7) } |
    Remove-Item -Force

# Clean .node leak (see #23095)
Remove-Item "$env:TEMP\.789*.node" -Force

# Clean claude-*-cwd leak (see #8856)
Get-ChildItem $env:TEMP -Filter 'claude-*-cwd' -Force | Remove-Item -Force