Reclaim disk space with an AI agent

Reclaim disk space with an AI agent — measured, tiered, and approved.

English · Türkçe · 简体中文 · Español · Русский · Português (BR) · 日本語

A battle-tested prompt that turns any AI coding agent (Claude Code, Cursor, Codex, …) into a careful disk-space auditor. It walks your disk top-down, groups findings by how much you'd regret deleting them, and waits for your approval before touching anything.

Works on macOS, Linux and Windows.

Because the biggest wins are rarely where you look first, and the obvious numbers lie:

• A Docker.raw reporting60 GB actually occupied14 GB . Deleting it based on the apparent size would have been a wrong call in the report.
• The real top offender was a 23 GB directory of deadgit worktrees from an abandoned refactor — invisible to any "clean your caches" checklist.
• Two 15 GB iOS simulator runtimes for OS versions nobody targets any more sat in/Library , which a plain home-directory scan never reaches.

The prompt encodes the method that finds those, plus the guardrails that keep an eager agent from deleting your .env.

Pick your language, open the file, and paste everything below the --- line into your agent. Answer the tier question when it comes, and run the elevated commands it hands you.

The prompt's language is functional, not cosmetic: it also sets the language the agent reports back in. Shell commands stay in English in every translation.

Nothing is deleted without your explicit approval — not even caches. If it deletes anything you did not name, that is a bug: stop it and open an issue.

The prompt asks for approval — it cannot enforce it. Stopping to ask is an instruction in the text; what actually guarantees the is your agent's permission mode. Run it somewhere tool calls need your confirmation (Claude Code's normal permission prompts, Cursor's ask mode, and so on) and not in an auto-approve / "yolo" mode. An agent running unattended can delete things before you have seen the tier table.

Read the tier table before you answer. The sizes it reports and its judgment of what is regenerable can both be wrong. You know what is on your disk; it is inferring from du output.

Deleting is irreversible. These commands do not move files to the trash. Have a backup you trust before you start, and especially before approving Tier 2 or Tier 3.

No warranty. This prompt is provided as is. The commands run on your machine, and the outcome is your responsibility.

Detect the OS — then use only that platform's commands and paths. 2. Measure, never guess — walk top-down to the actual culprit, not its parent. 3. Know the traps — sparse disks, double-counted symlinks, snapshots that hold freed space, async deletes,target/ dirs that aren't Rust. 4. Report in three tiers — and stop:Tier What Risk 1 Caches, build output, package downloads, dead worktrees Regenerable. None. 2 VM disks, old SDK runtimes, container images Real data inside goes away. 3 Downloads, browser profiles, unused apps Your call entirely. 5. Execute step by step — printing newly freed space after each one, and using each tool's own cleanup command instead ofrm -rf . 6. Respect the privilege boundary — anything needingsudo or elevation comes back to you as a ready-to-run command, never worked around. 7. Never delete source, git history,.env , keys, keychains, photo and mail stores, cloud-sync folders, running VM disks, or OS snapshots. 8. Summarize — including whatyou have to fix by hand afterwards.

macOS, 494 GB disk, 99% full with 5.2 GB left:

5.2 GB → 117 GB free. 99% → 71%. Two root-owned items (a 10 GB simulator dyld cache and a dead 6 GB Nessus install) were handed back as sudo one-liners rather than forced — exactly as the prompt requires.

prompts/
  disk-cleanup.en.md       English (source of truth)
  disk-cleanup.tr.md       Turkish
  disk-cleanup.zh-CN.md    Simplified Chinese
  disk-cleanup.es.md       Spanish
  disk-cleanup.ru.md       Russian
  disk-cleanup.pt-BR.md    Brazilian Portuguese
  disk-cleanup.ja.md       Japanese
README.md                  This file, plus one README per language

English is the source of truth. If a translation drifts from prompts/disk-cleanup.en.md, the English version wins. When changing the method, change the English prompt first, then port the change to the others.

New translations are welcome: copy disk-cleanup.en.md, keep every shell command exactly as it is, translate only the prose, and name the file with its BCP 47 code (disk-cleanup.<code>.md). Add a matching README.<code>.md and a row to the tables above.

The prompt tells the agent to treat everything it finds on disk as data, not instructions — a filename or a README inside some downloaded folder cannot talk it into deleting more. It also forbids working around sudo. Read the prompt before you run it; it is short on purpose.

Built by Rıza Sabuncu. If this saved you a weekend of disk archaeology, a coffee is appreciated.