Claude Code is quietly eating your disk — what’s in ~/.claude, what’s safe to delete, and the one setting that caps it

Published June 11, 2026 · 6 min read

This week someone on r/AI_Agents woke up to a nearly full SSD after leaving agents running overnight. It’s not a freak accident: Claude Code writes a transcript of every session, debug logs, and a snapshot of every file it edits — and never deletes any of it unless you tell it to. On our own machine, three weeks of heavy agent use left 732 MB in ~/.claude, 77% of it session transcripts. The bug report that documents the worst case lists a user with 300 GB of file snapshots. That report was closed as “not planned.”

The 30-second version

1. Run du -sh ~/.claude/* — transcripts in projects/ are almost certainly the bulk.
2. Add "cleanupPeriodDays": 14 to ~/.claude/settings.json. This is the only official retention control: session files older than N days are deleted at startup (default 30, minimum 1).
3. claude clean does not exist (verified on 2.1.172). Tutorials saying otherwise are describing a feature request, not a feature.
4. Don’t let the disk actually hit zero. A documented failure cascade corrupts .claude.json into a zero-length file, which wipes your settings and your login on next start.

What’s actually growing

Sizes from our machine after ~3 weeks of daily multi-agent use, plus the figures reported in the GitHub issue:

Path	What it is	Our machine	Reported in issue #24207
~/.claude/projects/	One JSONL transcript per session — every tool call, file read, and response, including subagents	565 MB	2,707 MB
~/.claude/plugins/	Installed plugins and their dependencies	103 MB	—
~/.claude/debug/	Debug logs, never cleaned automatically	small here	734 MB
~/.claude/file-history/	Snapshots of every file Claude edits (powers /rewind)	13 MB	188 MB — one user reported 300 GB
~/.claude/shell-snapshots/	Shell environment captures	1.1 MB	—
everything else	history, todos, caches, usage data	< 2 MB	~6 MB

Two leaks from the same report go beyond ~/.claude: a native .node addon that accumulated ~20 GB per week in temp storage, and thousands of claude-*-cwd marker files in the temp directory. If your numbers don’t add up inside ~/.claude, check $TMPDIR.

Long agent sessions are the multiplier. A single session transcript routinely crosses 10 MB; an overnight loop with subagents writes dozens of them.

The failure mode worth knowing about

Issue #24207 documents what happens if the disk actually fills: Claude Code tries to write .claude.json, the write fails and leaves a zero-length file, the next start reads it as invalid JSON and recreates defaults — taking your project settings and OAuth login with it. Running agents die mid-task. There’s no warning beforehand and no automatic recovery; you free space, re-authenticate, and restore settings from backup if you have one.

Anthropic closed the issue as not planned in February 2026. So the cap is on you. Here’s everything that actually works, in order of usefulness.

Fix 1 — the official setting

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

Per the official docs: session files older than this period are deleted at startup (default 30 days, minimum 1 — setting 0 is rejected). It also controls when orphaned subagent worktrees get removed.

Two caveats the docs are explicit about, and one they’re silent on:

• Cleanup runs at startup — a machine that runs one long-lived session for weeks never triggers it.
• Deleting old session files means --resume and --continue can’t reach those conversations anymore.
• The docs only promise cleanup of session files. debug/ and file-history/ retention is not documented — treat those as manual territory.

If you don’t want transcripts at all: set the CLAUDE_CODE_SKIP_PROMPT_HISTORY environment variable, or in scripted/-p runs pass --no-session-persistence. You lose resumability; CI jobs and one-shot automations rarely care.

Fix 2 — two find commands

Safe to run anytime; they touch only regenerable data:

# transcripts older than 14 days
find ~/.claude/projects -name '*.jsonl' -mtime +14 -delete

# edit snapshots older than 14 days (kills /rewind for those sessions only)
find ~/.claude/file-history -type f -mtime +14 -delete

What you must not delete: ~/.claude/settings.json, ~/.claude.json (note: it lives in $HOME, not inside ~/.claude), anything named .credentials*, your memory/ directory, and CLAUDE.md files. Those are configuration and login state, not cache.

Fix 3 — the third-party cleaners

Two open-source tools wrap the same idea with a preview step:

Tool	Shape	What it adds
claude-code-cleaner	Rust TUI	Detects orphaned project caches (deleted repos whose transcripts remain), expiry filters, dry-run
claude-clean	CLI	Size report per directory, preview before deletion, age-based cleanup

Both are fine; neither is necessary once cleanupPeriodDays is set and you know the two find commands.

What doesn’t exist

• claude clean — not a command in 2.1.172. It’s feature request #11646, open since 2025. At least one tutorial site documents it as if it shipped; it didn’t.
• A disk-usage warning — Claude Code will write until the OS refuses.
• A size cap — there is no setting that bounds ~/.claude by megabytes; the only lever is age.

Companion reading

• What AI coding agents actually write to your disk — the full eight-agent map this guide zooms in from, including Codex, Cursor, and Gemini equivalents.
• Claude Code usage limits, explained — the other meter that fills up: rate windows, weekly caps, and how to watch your burn.

Sources

1. GitHub issue #24207 — No disk space management: ~/.claude grows unbounded, cascade failure destroys settings and auth at 0 bytes free
2. GitHub issue #11646 — Add claude clean command
3. Claude Code settings documentation — cleanupPeriodDays
4. r/AI_Agents — “Claude Code filled almost my entire SSD with random nonsense overnight” (June 11, 2026)
5. claude-code-cleaner (GarrickZ2)
6. claude-clean (hoangvu12)

FAQ

Does /compact free disk space? No. /compact shrinks the conversation context inside the current session; the transcript on disk keeps growing. Disk and context are different meters.

Is it safe to delete ~/.claude/projects entirely? Yes, if you don’t need --resume or --continue for any past session. Login and settings live elsewhere (~/.claude.json, settings.json) and are untouched.

Why did my disk fill overnight? Long-running agent loops write transcripts continuously, plus a file snapshot for every edit. Multi-agent setups multiply this by the number of subagents. Check du -sh ~/.claude/projects/* and $TMPDIR for claude-* files.

Does cleanupPeriodDays clean debug logs and file-history too? Not per the documentation — it promises cleanup of session files only. Prune debug/ and file-history/ manually with the find commands above.