{"slug": "reclaim-disk-space-with-an-ai-agent", "title": "Reclaim disk space with an AI agent", "summary": "A GitHub project from developer riza, ai-disk-cleanup, publishes a reusable prompt that turns AI coding agents such as Claude Code, Cursor and Codex into a disk-space auditor that measures usage top-down, sorts findings into three deletion-risk tiers and waits for explicit user approval before deleting anything on macOS, Linux or Windows. The project's examples show why apparent sizes mislead: a Docker.raw file reporting 60 GB actually occupied 14 GB, while the real top offender was a 23 GB directory of dead git worktrees, and two 15 GB iOS simulator runtimes for untargeted OS versions sat in /Library outside a home-directory scan. The README warns the prompt cannot enforce its own approval step, so users must run it in an agent permission mode that requires confirmation rather than auto-approve, and that deletions are irreversible with no warranty.", "body_md": "**Reclaim disk space with an AI agent — measured, tiered, and approved.**\n\n**English** · [Türkçe](https://github.com/riza/ai-disk-cleanup/blob/main/README.tr.md) · [简体中文](https://github.com/riza/ai-disk-cleanup/blob/main/README.zh-CN.md) · [Español](https://github.com/riza/ai-disk-cleanup/blob/main/README.es.md) · [Русский](https://github.com/riza/ai-disk-cleanup/blob/main/README.ru.md) · [Português (BR)](https://github.com/riza/ai-disk-cleanup/blob/main/README.pt-BR.md) · [日本語](https://github.com/riza/ai-disk-cleanup/blob/main/README.ja.md)\n\nA battle-tested prompt that turns any AI coding agent (Claude Code, Cursor, Codex, …)\ninto a careful disk-space auditor. It walks your disk top-down, groups findings by how\nmuch you'd regret deleting them, and **waits for your approval before touching anything**.\n\nWorks on **macOS, Linux and Windows**.\n\nBecause the biggest wins are rarely where you look first, and the obvious numbers lie:\n\n- A `Docker.raw` reporting**60 GB** actually occupied**14 GB** . Deleting it based on\nthe apparent size would have been a wrong call in the report.\n- The real top offender was a **23 GB** directory of dead`git` worktrees from an\nabandoned refactor — invisible to any \"clean your caches\" checklist.\n- Two **15 GB** iOS simulator runtimes for OS versions nobody targets any more sat in`/Library` , which a plain home-directory scan never reaches.\n\nThe prompt encodes the method that finds those, plus the guardrails that keep an\neager agent from deleting your `.env`.\n\nPick your language, open the file, and paste everything below the `---` line into your\nagent. Answer the tier question when it comes, and run the elevated commands it hands you.\n\n| Language | Prompt | \n|---|---|\n| English | [`prompts/disk-cleanup.en.md`](https://github.com/riza/ai-disk-cleanup/blob/main/prompts/disk-cleanup.en.md) | \n| Türkçe | [`prompts/disk-cleanup.tr.md`](https://github.com/riza/ai-disk-cleanup/blob/main/prompts/disk-cleanup.tr.md) | \n| 简体中文 | [`prompts/disk-cleanup.zh-CN.md`](https://github.com/riza/ai-disk-cleanup/blob/main/prompts/disk-cleanup.zh-CN.md) | \n| Español | [`prompts/disk-cleanup.es.md`](https://github.com/riza/ai-disk-cleanup/blob/main/prompts/disk-cleanup.es.md) | \n| Русский | [`prompts/disk-cleanup.ru.md`](https://github.com/riza/ai-disk-cleanup/blob/main/prompts/disk-cleanup.ru.md) | \n| Português (BR) | [`prompts/disk-cleanup.pt-BR.md`](https://github.com/riza/ai-disk-cleanup/blob/main/prompts/disk-cleanup.pt-BR.md) | \n| 日本語 | [`prompts/disk-cleanup.ja.md`](https://github.com/riza/ai-disk-cleanup/blob/main/prompts/disk-cleanup.ja.md) | \n\nThe 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.\n\n**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](https://github.com/riza/ai-disk-cleanup/issues).\n\n**The prompt asks for approval — it cannot enforce it.** Stopping to ask is an\ninstruction in the text; what actually guarantees the pause is your agent's permission\nmode. Run it somewhere tool calls need your confirmation (Claude Code's normal permission\nprompts, Cursor's ask mode, and so on) and **not** in an auto-approve / \"yolo\" mode. An\nagent running unattended can delete things before you have seen the tier table.\n\n**Read the tier table before you answer.** The sizes it reports and its judgment of what\nis regenerable can both be wrong. You know what is on your disk; it is inferring from\n`du` output.\n\n**Deleting is irreversible.** These commands do not move files to the trash. Have a backup\nyou trust before you start, and especially before approving Tier 2 or Tier 3.\n\n**No warranty.** This prompt is provided as is. The commands run on your machine, and the\noutcome is your responsibility.\n\n1. \n**Detect the OS** — then use only that platform's commands and paths.\n2. \n**Measure, never guess** — walk top-down to the actual culprit, not its parent.\n3. \n**Know the traps** — sparse disks, double-counted symlinks, snapshots that hold\nfreed space, async deletes,`target/` dirs that aren't Rust.\n4. \n**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.\n5. \n**Execute step by step** — printing newly freed space after each one, and using\neach tool's own cleanup command instead of`rm -rf` .\n6. \n**Respect the privilege boundary** — anything needing`sudo` or elevation comes\nback to you as a ready-to-run command, never worked around.\n7. \n**Never delete** source, git history,`.env` , keys, keychains, photo and mail\nstores, cloud-sync folders, running VM disks, or OS snapshots.\n8. \n**Summarize** — including what*you* have to fix by hand afterwards.\n\nmacOS, 494 GB disk, **99% full with 5.2 GB left**:\n\n| Step | Freed | \n|---|---|\n| Dead Claude/git worktrees in one project | 4.9 GB | \n| Rust `target/` directories | 5.7 GB | \n| 83 × `node_modules` +`.next` caches | 18 GB | \n| `~/Library/Caches` (17 GB → 2.4 GB) | 14 GB | \n| `~/.cache` , npm, Go modcache, Homebrew | 16 GB | \n| iOS 17.5 + 18.0 simulator runtimes | 36 GB | \n| Docker Desktop VM disk | 14 GB | \n| OrbStack VM disk | 11 GB | \n| Downloads: an 11 GB firmware image + 42 installers | 14 GB | \n| **Total** | **≈111 GB** | \n\n**5.2 GB → 117 GB free. 99% → 71%.** Two root-owned items (a 10 GB simulator `dyld`\ncache and a dead 6 GB Nessus install) were handed back as `sudo` one-liners rather\nthan forced — exactly as the prompt requires.\n\n```\nprompts/\n  disk-cleanup.en.md       English (source of truth)\n  disk-cleanup.tr.md       Turkish\n  disk-cleanup.zh-CN.md    Simplified Chinese\n  disk-cleanup.es.md       Spanish\n  disk-cleanup.ru.md       Russian\n  disk-cleanup.pt-BR.md    Brazilian Portuguese\n  disk-cleanup.ja.md       Japanese\nREADME.md                  This file, plus one README per language\n```\n\n**English is the source of truth.** If a translation drifts from\n`prompts/disk-cleanup.en.md`, the English version wins. When changing the method, change\nthe English prompt first, then port the change to the others.\n\nNew translations are welcome: copy `disk-cleanup.en.md`, keep every shell command exactly\nas it is, translate only the prose, and name the file with its BCP 47 code\n(`disk-cleanup.<code>.md`). Add a matching `README.<code>.md` and a row to the tables above.\n\nThe prompt tells the agent to treat everything it finds on disk as **data, not\ninstructions** — a filename or a README inside some downloaded folder cannot talk it\ninto deleting more. It also forbids working around `sudo`. Read the prompt before you\nrun it; it is short on purpose.\n\nBuilt by **Rıza Sabuncu**. If this saved you a weekend of disk archaeology, a coffee is appreciated.", "url": "https://wpnews.pro/news/reclaim-disk-space-with-an-ai-agent", "canonical_source": "https://github.com/riza/ai-disk-cleanup", "published_at": "2026-10-25 19:31:08+00:00", "updated_at": "2026-10-25 19:42:19.025023+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools"], "entities": ["riza", "ai-disk-cleanup", "GitHub", "Claude Code", "Cursor", "Codex", "Docker.raw"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/reclaim-disk-space-with-an-ai-agent", "markdown": "https://wpnews.pro/news/reclaim-disk-space-with-an-ai-agent.md", "text": "https://wpnews.pro/news/reclaim-disk-space-with-an-ai-agent.txt", "jsonld": "https://wpnews.pro/news/reclaim-disk-space-with-an-ai-agent.jsonld"}}