ai-disk-cleanup

ai-disk-cleanup is a prompt by Rıza Sabuncu that turns AI coding agents such as Claude Code, Cursor and Codex into disk-space auditors. It walks the disk top-down, groups findings by how much deletion would be regretted, and waits for explicit approval before removing anything. It works on macOS, Linux and Windows, and is published in seven languages.

What It Is

The project is a prompt, not an application. The user opens the prompt file for their language, pastes the content below the divider into an agent, answers the tier question, and runs any elevated commands the agent hands back. The prompt language also sets the language the agent reports in, while shell commands stay in English.

How the cleanup method works

The agent first detects the OS and uses only that platform's commands and paths. It measures instead of guessing, drilling down to the actual culprit rather than its parent directory, and it is told about traps such as sparse disks, double-counted symlinks, snapshots that hold freed space, and async deletes. Findings are reported in three tiers and the agent then stops:

• Tier 1: caches, build output, package downloads and dead worktrees, which are regenerable.
• Tier 2: VM disks, old SDK runtimes and container images, where real data is lost.
• Tier 3: downloads, browser profiles and unused apps, which are entirely the user's call.

Approved items are executed step by step, printing newly freed space after each one and using each tool's own cleanup command rather than rm -rf. Anything needing sudo or elevation is returned as a ready-to-run command instead of being worked around. The prompt forbids deleting source, git history, .env files, keys, keychains, photo and mail stores, cloud-sync folders, running VM disks, and OS snapshots.

Safety notes

The README states the prompt asks for approval but cannot enforce it; the agent's permission mode is what guarantees the pause, so it should not be run in an auto-approve mode. Deletions are irreversible, the reported sizes and regenerability judgments can be wrong, and a backup is recommended. The prompt also instructs the agent to treat file contents found on disk as data, not instructions. The README documents one example run on a macOS disk that freed about 111 GB.