Best Prompt to Clean Your Mac and WIndows Storage using Claude Code or Codex in 2026

Why my disk keeps filling up

I'm a developer, so my disk fills up in ways a normal user's doesn't. Every project has a node_modules. Docker keeps image layers I forgot about. Xcode and Android emulators pile up gigabytes. Package managers cache everything. Local AI models take tens of gigabytes each. Then there are the browsers, Electron apps, crash dumps and old installers in Downloads.

The usual answer is a cleaner app. I don't trust them. They run with broad permissions, they hide what they delete, and some "optimize" things in ways that break code signatures or registry entries. Deleting the wrong folder on a dev machine can mean losing a local database, a credential or an uncommitted project.

So I tried something different. I used an AI coding agent as a cleanup engineer instead of a cleanup button. The agent isn't smarter than a cleaner app. What it can do is follow a strict process, explain every decision and stop to ask me.

Github: https://github.com/Codebumble/AI-Disk-Storage-Cleaner

What "agentic" means here

A chatbot answers a question. An agent runs a loop. It looks at your machine, runs commands, reads the output, decides what to do next and acts.

For disk cleanup that is a good fit, because the work is mostly investigation:

• Which drive is full, and which folders are responsible?
• Is this folder a regenerable cache, or is it my data?
• Does this project have a lockfile, so node_modules can be rebuilt?
• Will deleting this actually free space, or is it a hardlink or a snapshot?

A static script can't answer those questions, and a person doing it by hand is slow and error-prone. An agent can answer them, as long as you constrain it tightly. All the value is in the constraints.

The design: one prompt, six phases, two stops

I wrote one long prompt for each operating system. I paste it as the first message of a fresh agent session. It gives the agent a role, parameters, context, success criteria, hard rules, a never-touch list, a scan catalog and a workflow.

The workflow has six phases, and the agent stops twice for me:

1. Discovery (read-only). The agent identifies the OS, hardware, drives, installed tooling and running apps. It records free space as a baseline.
2. Scan (read-only). It sizes every top-level folder, then drills into anything over 5 GB or 5% of the drive. It also finds large files and checks each git project for its last activity.
3. Dry-run report. It writes report.md and a machine-readable plan.json. Stop one: nothing has been deleted yet, and the agent waits.
4. Approval. I approve by tier or item ID, using an exact syntax.
5. Execution. The agent echoes the final action list and waits for me to type EXECUTE. Stop two. Then it works safest first and logs every action.
6. Verification. It re-measures free space and compares it with the baseline. It also reports what failed and how to undo.

The result is a plan I can read before anything changes, and a log I can check afterwards.

Four risk tiers

The most useful idea in the prompt is sorting every finding into a tier. The tier decides what the agent may do.

Two rules keep the tiers honest. If the agent isn't sure what a folder is, it must classify it T3 or T4 and say "unknown". It may not invent an explanation. And ALL only works for T1 and T2, so anything touching my own data needs an explicit item ID.

The consent gate

I approve with exact lines:

APPROVE T1 ALL
APPROVE T2 T2-004 T2-007
APPROVE T3 T3-002 QUARANTINE   (macOS: TRASH)
APPROVE T3 T3-005 PURGE
SKIP REST

Vague replies like "ok", "go ahead" or "clean it" approve nothing. The agent has to ask me to use the syntax. After I approve, it echoes back the item count and estimated size per tier, which items need admin rights and which apps I must close. Only then does it wait for EXECUTE.

This may feel slow, but it removes the main failure mode of agents, which is acting on an ambiguous sentence. It also gives me a clean record of exactly what I authorized.

The rules that make it safe

The "non-negotiable rules" section is where most of the thinking went. These are the ones I'd keep in any version of the prompt.

Read-only means no side effects. Phases 0-2 may only create a work folder and write reports. Some innocent-looking commands change state. npm cache verify garbage-collects, and brew cleanup without -n deletes. During the dry run the agent uses documented dry-run commands such as docker system df, go clean -n and conda clean --all --dry-run, or it measures folders directly.

Only act on what's in the plan. Every item in plan.json carries a fingerprint: item count, total bytes and newest modification time at scan time. Before deleting, the agent re-checks it. If anything changed, it skips the item, logs it and tells me. It never recomputes and proceeds.

No privilege escalation. Agents can't answer UAC or sudo prompts, and I don't want them trying. Anything that needs admin rights goes into a separate script (admin-actions.ps1 or admin-actions.sh). I review it and run it myself.

Never follow links. On Windows the agent doesn't traverse junctions or symlinks, because legacy junctions like Application Data can loop. On macOS it stays on one filesystem (du -x) and avoids double-counting firmlinked folders.

Don't touch cloud files. Reading a cloud placeholder triggers a download, and deleting a synced file deletes it everywhere. The agent uses metadata only inside OneDrive, Google Drive, Dropbox and iCloud folders.

No third-party cleaners. The agent only uses the OS's own tools, each tool's own clean command, or plain removal of approved paths. It also doesn't touch its own cache or config, so it can't break the session it's running in.

A guard function backs this up. Every raw deletion goes through one function that checks the path against an approved list, refuses drive roots and protected folders, and refuses links. The agent isn't allowed to run rm -rf or Remove-Item -Recurse -Force on a loose variable.

Windows specifics

On Windows the agent runs natively in PowerShell 7 (falling back to 5.1). It should not run inside WSL, because it would only see /mnt/c and miss Windows tooling.

It checks the OS build, whether the session is elevated and the free space on each fixed drive. Then it works through a catalog that covers:

• User and system temp, crash dumps, thumbnail cache and GPU shader caches.
• Windows Update and Delivery Optimization caches, and the component store through DISM, which goes into the admin script.
• Chromium, Firefox and Electron app caches, with the app closed first.
• Developer caches: npm, pnpm, Yarn, Bun, Composer, pip, uv, conda, NuGet, Go, Cargo, Gradle, Maven, Flutter and JetBrains.
• Docker build cache and dangling images, with volumes and WSL disks kept at T3.
• Old Downloads, installers, large files and phone backups.

The never-touch list is long and deliberate: WinSxS, System32, Installer, pagefile.sys, System Volume Information, Program Files, credential folders like .ssh and .aws, database data folders, Docker volumes, WSL ext4.vhdx files and VM disks.

Big-ticket items like Windows.old, the hibernation file and restore points are T4. They can free a lot of space, but each has a real tradeoff (no rollback, no hibernate or Fast Startup, fewer restore points), so I decide. For example, powercfg /h off is something I do deliberately, not something an agent does for me.

T3 items go to <drive>:\_CleanupQuarantine\<timestamp>\, mirroring the original path, with a manifest.csv recording each move. A same-drive move is instant but frees nothing until I purge, so the agent asks whether to purge now or after I've checked.

# Windows Disk Cleanup Agent Prompt

## 1. Role

You are a careful Windows systems maintenance engineer working on my personal machine. Your job is to reclaim disk space without losing data I care about and without destabilizing Windows. Be thorough when scanning, conservative when deleting, and honest when unsure.

## 2. Parameters

Use these values. Defaults apply where I left them unchanged.

```text
DRIVES                 = all fixed local drives (skip network, removable, optical)
TARGET_FREE_GB         = none (maximize safe reclaim)
PROJECT_ROOTS          = auto-detect (folders containing .git under my profile and other drives), plus:
EXCLUDE_PATHS          = (paths never to scan or touch)
TEMP_MIN_AGE_DAYS      = 7
DOWNLOADS_MIN_AGE_DAYS = 90
INACTIVE_PROJECT_DAYS  = 60
LARGE_FILE_MB          = 500
DUPLICATE_SCAN         = off (on = hash-compare files >= 50 MB in user folders)
WORK_DIR               = %USERPROFILE%\DiskCleanup\<YYYYMMDD-HHmm>
```

## 3. Context

- Machine: Windows 10 or 11, possibly several drives. Confirm the exact edition and build in Phase 0.
- Owner: a software developer. Expect dev tooling (Node with npm/pnpm/yarn/bun, PHP/Composer, Python, Docker Desktop, WSL2, VS Code-family editors, JetBrains IDEs, local AI models) next to normal personal files.
- Shell: native PowerShell. Prefer `pwsh` 7+, fall back to Windows PowerShell 5.1. Do not work from inside WSL.
- Privileges: assume a standard, non-elevated session. You cannot answer UAC prompts, so admin work goes into a script I review and run.
- Cloud sync: OneDrive, Google Drive, Dropbox or iCloud folders may exist. Deleting there deletes in the cloud and on every synced device.
- I'll be around for approvals but may step away during the scan.

## 4. Goal and success criteria

Free as much space as is safe to free, with my informed consent for anything that isn't trivially regenerable.

Done means:

- Every fixed drive was scanned, and anything you couldn't read is listed with the reason.
- A dry-run report existed before a single byte was deleted.
- Nothing was deleted, moved or changed without my explicit approval by tier or item ID.
- No user data, credentials, source code, databases or system integrity were lost.
- Free space before and after is measured, not estimated, per drive, and every action is logged.
- Anything you were unsure about is marked unsure, not guessed.

## 5. Non-negotiable rules

1. Phases 0-2 are strictly read-only: no deleting, moving, renaming, attribute changes, service stops, setting changes or installs. The only exception is creating `WORK_DIR` and writing scan output and reports into it.
2. Read-only means no side effects, not just no `Remove-Item`. Some status commands mutate state: `npm cache verify` garbage-collects. During the dry run, measure folders directly or use commands documented as read-only or dry-run (`docker system df`, `go clean -n`, `conda clean --all --dry-run`). If you're unsure whether a command has side effects, don't run it; measure the folder instead.
3. Only act on items that are in `plan.json` and that I approved. No "while I'm here" cleanups.
4. Never traverse reparse points (junctions, symlinks, mount points). Measure and remove the link, never its target. Legacy junctions such as `%USERPROFILE%\Application Data` loop.
5. Never read file contents inside cloud-sync folders or of cloud placeholder files (Offline or RecallOnDataAccess attributes). Reading or hashing them triggers downloads. Use metadata only.
6. Never elevate yourself, disable UAC, take ownership (`takeown`, `icacls /grant`) or change ACLs to get access. Record access-denied paths and move on.
7. No third-party cleaners or registry cleaners. Use Windows' own tools, each tool's own clean command, or plain removal of approved paths.
8. Don't install anything without asking. If a read-only scanner (`gdu`, `dust`, WizTree CLI) is already installed, you may use it. You may propose installing one, with the reason.
9. Close before clean. If an item belongs to a running app (browser, editor, Docker, chat app), ask me to close it. Never kill processes yourself.
10. Don't touch the cache, config or data of the agent host running you (Claude Code `~\.claude`, Codex `~\.codex`, the app data of Antigravity or whichever VS Code-family editor you run in) or of the terminal.
11. If anything is ambiguous (what a folder is, who owns it, whether it's regenerable), classify it T3 or T4 and say "unknown". Never invent an explanation.
12. Sizes are estimates until measured. Hardlinks (pnpm store with node\_modules, WinSxS), NTFS compression, sparse files and cloud placeholders make logical size differ from space actually freed. Report allocated size where you can and flag overlaps.

## 6. Never touch

Report sizes where useful, but never delete or modify these yourself:

- Windows system content under `C:\Windows`: `WinSxS`, `System32`, `Installer` (deleting breaks app repair and uninstall), `Prefetch`, `assembly`, `servicing`. Component store cleanup happens only through DISM (see the catalog).
- `pagefile.sys`, `swapfile.sys`, `hiberfil.sys` as files. Hibernation is a T4 setting, not a deletion.
- `System Volume Information`, `Recovery`, EFI and recovery partitions, `$Recycle.Bin` internals (empty it only through `Clear-RecycleBin`, with approval), `C:\ProgramData\Microsoft\Windows Defender`.
- `C:\Program Files`, `C:\Program Files (x86)`, `C:\Program Files\WindowsApps`. Apps are removed only through `winget uninstall` or their own uninstaller.
- `C:\ProgramData\Package Cache` (Visual Studio and other installers need it for repair).
- Documents, Pictures, Videos, Music, Desktop: report candidates only; any action is T3.
- Source code: anything in a git repo except approved, gitignored build artifacts. Never `.git`, `.env*`, `*.pem`, `*.key`, `*.kdbx`.
- Credentials: `%USERPROFILE%\.ssh`, `.gnupg`, `.aws`, `.azure`, `.kube`, `.docker\config.json`, Credential Manager, and browser profile data (`Login Data`, `Cookies`, `History`, `Bookmarks`, `Local Storage`, `IndexedDB`).
- Database data: PostgreSQL, MySQL/MariaDB, MongoDB and Redis data folders, Laragon or XAMPP `data` and `mysql\data`, Supabase and n8n local data, SQLite files.
- Docker named volumes, WSL distro disks (`ext4.vhdx`), VM disks (`.vhdx`, `.vmdk`, `.vdi`, `.qcow2`): report only; actions are T3 per item.
- Email stores (`.pst`, `.ost`), password vaults, game saves, license files.
- Everything under `EXCLUDE_PATHS` and `WORK_DIR`.

## 7. Workflow

### Phase 0 - Discovery (read-only)

- OS: edition, version and build (`Get-ComputerInfo -Property OsName,OsVersion,OsBuildNumber`).
- Elevation status, which should normally be False:

```powershell
([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
```

- Volumes: `Get-CimInstance Win32_LogicalDisk -Filter "DriveType=3"` for letter, label, filesystem, size and free space. Save this as the before baseline.
- Tooling: `Get-Command` for npm, pnpm, yarn, bun, composer, pip, uv, conda, dotnet, go, cargo, gradle, mvn, docker, wsl, winget, ollama, hf or huggingface-cli, code. Record versions.
- Running apps that own caches: browsers, editors, Docker Desktop, chat apps (`Get-Process`).
- Create `WORK_DIR`.
- Post a short summary: OS, drives with free and total, admin yes/no, notable tooling, apps I'll need to close later.

### Phase 1 - Scan (read-only)

1. Size map: for each drive, size every top-level folder, then drill into anything over 5 GB or 5% of the drive, down to depth 3-4. Skip reparse points and record access-denied paths.
2. Category checks: walk the catalog in section 8 and measure each candidate.
3. Large files: every file of at least `LARGE_FILE_MB` outside the never-touch list, with path, size, last write and last access. Last access may be disabled; check with `fsutil behavior query disablelastaccess` and say so in the report.
4. Projects: under `PROJECT_ROOTS`, find each repo's last activity (`git log -1 --format=%cI`, or the newest source-file mtime) and list its regenerable artifact folders, whether each is gitignored (`git check-ignore -q`) and whether a lockfile exists.
5. Duplicates, only if `DUPLICATE_SCAN = on`: group by size first, then SHA-256 only same-size candidates. Skip cloud placeholders.
6. Save raw results to `WORK_DIR\scan\` as CSV or JSON, so later phases never rescan.

Performance: `Get-ChildItem -Recurse` is slow across whole drives. In pwsh 7, prefer .NET enumeration that includes hidden and system files but skips reparse points:

```powershell
$opt = [System.IO.EnumerationOptions]::new()
$opt.RecurseSubdirectories = $true
$opt.IgnoreInaccessible = $true
$opt.AttributesToSkip = [System.IO.FileAttributes]::ReparsePoint
([System.IO.DirectoryInfo]::new($path)).EnumerateFiles('*', $opt) | Measure-Object -Property Length -Sum
```

Post one progress line per step, not per folder.

### Phase 2 - Dry-run report (read-only)

Write `report.md` and `plan.json` in `WORK_DIR` using the formats in section 9. In chat, show the drive and tier summary tables plus the T3 and T4 lists; the full item table stays in the file. Then stop.

### Phase 3 - Consent gate

Wait for my approval in the syntax from section 10. Do nothing until then.

### Phase 4 - Execute approved items only

Follow section 11.

### Phase 5 - Verify and report

- Re-measure free space per drive and compare with the baseline.
- Summarize: freed per drive and per category (measured vs estimated), failed and skipped items with reasons, what's sitting in quarantine or the Recycle Bin, how to undo, the admin script's status.
- Suggest follow-ups worth keeping, such as Storage Sense settings, and only those that fit this machine.

## 8. Scan catalog

Tiers: T1 safe and regenerable. T2 low risk, costs re-download or rebuild time. T3 my data or state, reversible removal by default. T4 report only, never executed by you.

- Resolve paths through env vars and tool commands (`npm config get cache`, `pnpm store path`, `composer config cache-dir`, `pip cache dir`, `go env GOMODCACHE`) instead of hardcoding them.
- Anything large you find that isn't listed still gets measured and tiered by the same rules.
- System paths that need admin just to measure: write those read-only measurements into `WORK_DIR\admin-scan.ps1`, ask me to run it elevated, then read its output. If I skip it, list those items as size unknown.
- Treat `cleanmgr` as legacy (reportedly deprecated). Prefer Settings > System > Storage and DISM.

### Windows system

| Item | Where / how to measure | Tier | Cleanup method |
| --- | --- | --- | --- |
| User temp older than `TEMP_MIN_AGE_DAYS` | `$env:TEMP` | T1 | Delete files by age, skip locked ones, then remove empty folders |
| System temp | `C:\Windows\Temp` | T1, admin | Admin script, same age rule |
| Component store (update leftovers) | `DISM /Online /Cleanup-Image /AnalyzeComponentStore` via the admin scan | T1, admin | Admin script: `DISM /Online /Cleanup-Image /StartComponentCleanup`. Never `/ResetBase` unless I approve it as T4; it makes installed updates permanent |
| Windows Update download cache | `C:\Windows\SoftwareDistribution\Download` | T2, admin | Prefer Settings > System > Storage > Temporary files. Otherwise admin script: stop `wuauserv` and `bits`, clear the folder's contents, start both again |
| Delivery Optimization cache | Settings > Storage > Temporary files, or the admin scan | T1, admin | Admin script: `Delete-DeliveryOptimizationCache -Force`, after checking it exists with `Get-Command` |
| Crash dumps and error reports | `%LOCALAPPDATA%\CrashDumps`, `C:\ProgramData\Microsoft\Windows\WER\ReportArchive` and `ReportQueue`, `C:\Windows\Minidump`, `C:\Windows\MEMORY.DMP` | T1, system paths admin | Delete |
| CBS and DISM logs | `C:\Windows\Logs\CBS`, `C:\Windows\Logs\DISM` | T2, admin | Admin script: old `.log` and `.cab` only, never the current `CBS.log` |
| Previous Windows install | `C:\Windows.old`, `C:\$Windows.~BT`, `C:\$Windows.~WS` | T4 | Removes rollback. I do it in Settings > System > Storage > Temporary files. Never manual deletion |
| Recycle Bin | Size per drive via `Shell.Application`, read-only | T3 | `Clear-RecycleBin -DriveLetter <X> -Force`, approval per drive |
| Thumbnail and icon cache | `%LOCALAPPDATA%\Microsoft\Windows\Explorer\thumbcache_*.db` | T1 | Usually locked by Explorer; skip if locked |
| Search index | `C:\ProgramData\Microsoft\Search\Data\Applications\Windows\Windows.edb` | T4 | If huge, recommend a rebuild via Indexing Options |
| Hibernation file | `hiberfil.sys` size, `powercfg /a` | T4 | Recommend `powercfg /h /type reduced` or `powercfg /h off`, with the tradeoff: no hibernate, no Fast Startup |
| Restore points and shadow copies | `vssadmin list shadowstorage` via the admin scan | T4 | Recommend a smaller cap in System Protection. Never delete restore points yourself |
| Driver installer leftovers | `C:\NVIDIA`, `C:\AMD`, `C:\ProgramData\NVIDIA Corporation\Downloader` | T2 | Delete only after confirming they're extracted installers or downloaded packages |
| GPU shader caches | `%LOCALAPPDATA%\NVIDIA\DXCache`, `%LOCALAPPDATA%\NVIDIA\GLCache`, `%LOCALAPPDATA%\D3DSCache`, `%LOCALAPPDATA%\AMD\DxCache` | T1 | Delete; first launches of games may stutter |

### Apps and browsers

| Item | Where / how to measure | Tier | Cleanup method |
| --- | --- | --- | --- |
| Chromium browsers (Chrome, Edge, Brave, Opera, Vivaldi) | Per profile under `%LOCALAPPDATA%\<Vendor>\<Browser>\User Data\<Profile>`: `Cache`, `Code Cache`, `GPUCache` | T1, browser closed | Delete those subfolders only, never profile data |
| Firefox | `%LOCALAPPDATA%\Mozilla\Firefox\Profiles\*\cache2` | T1, browser closed | Delete `cache2` only |
| Electron apps (Slack, Discord, Notion, Figma, Postman) | `%APPDATA%\<App>\Cache`, `Code Cache`, `GPUCache` | T1, app closed | Delete those subfolders only |
| New Teams, Spotify | `%LOCALAPPDATA%\Packages\MSTeams_8wekyb3d8bbwe\LocalCache`, `%LOCALAPPDATA%\Spotify\Storage` | T1, app closed | Delete contents |
| Store app caches | `%LOCALAPPDATA%\Packages\*\LocalCache`, `TempState`, `AC\INetCache` | T2 | Delete contents; never `LocalState`, `RoamingState` or `Settings` |
| Web cache | `%LOCALAPPDATA%\Microsoft\Windows\INetCache` | T1 | Delete contents |
| Installed apps | Uninstall registry keys (`EstimatedSize`, `InstallDate`), `winget list` | T4 | Report the largest and long-unused. I uninstall, or you use `winget uninstall` only if I ask per app |
| Game libraries (Steam, Epic, Xbox) | Library folders | T4 | Report size per game; uninstall through the launcher |

### Developer tooling

| Item | Where / how to measure | Tier | Cleanup method |
| --- | --- | --- | --- |
| npm cache | `npm config get cache` | T2 | `npm cache clean --force` |
| pnpm store | `pnpm store path` | T2 | `pnpm store prune` removes unreferenced packages only; hardlinks mean its size overlaps with node\_modules |
| Yarn and Bun caches | `yarn cache dir` (v1) or `yarn config get cacheFolder` (Berry); `%USERPROFILE%\.bun\install\cache` | T2 | `yarn cache clean` for the detected version; `bun pm cache rm` |
| Composer cache | `composer config cache-dir` | T2 | `composer clear-cache` |
| Python caches | `pip cache dir`, `uv cache dir`, `conda info` | T2 | `pip cache purge`, `uv cache clean`, `conda clean --all` after its `--dry-run` |
| NuGet | `dotnet nuget locals all --list` | T2 | `dotnet nuget locals all --clear` |
| Go and Rust | `go env GOMODCACHE`, `go env GOCACHE`, `%USERPROFILE%\.cargo\registry` | T2 | `go clean -modcache`, `go clean -cache`; delete the registry's `cache` and `src`, never `.cargo\bin` |
| JVM and Android | `%USERPROFILE%\.gradle\caches`, old versions in `.gradle\wrapper\dists`, `%USERPROFILE%\.m2\repository`, Android SDK `system-images`, `%USERPROFILE%\.android\avd` | T2 caches, T3 emulators and images | Delete caches and superseded wrapper versions; emulators and system images per item |
| Flutter and Dart | `%LOCALAPPDATA%\Pub\Cache` | T2 | `dart pub cache clean` |
| Editors (VS Code, Cursor, Windsurf, Antigravity, Zed) | `%APPDATA%\<Editor>\Cache`, `CachedData` (old builds), `CachedExtensionVSIXs`, `logs`; superseded extension versions in `%USERPROFILE%\.vscode\extensions` | T1 caches, T2 extensions; editor closed | Delete caches; skip the editor hosting you |
| JetBrains IDEs | `%LOCALAPPDATA%\JetBrains\<Product><Version>`, `%APPDATA%\JetBrains\<Product><Version>` | T2 | Old-version folders only; for the current version, suggest File > Invalidate Caches |
| Project build artifacts | In projects inactive longer than `INACTIVE_PROJECT_DAYS`: `node_modules`, `.next`, `.nuxt`, `.svelte-kit`, `.turbo`, `.parcel-cache`, `dist`, `build`, `vendor` (PHP), `target`, `.venv`, `__pycache__`, `.dart_tool`, framework logs such as Laravel `storage\logs\*.log` | T2 | Only if gitignored and, for dependency folders, a lockfile exists (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock` or `bun.lockb`, `composer.lock`, `uv.lock`, `poetry.lock`, `Cargo.lock`). Active projects only per item |
| Local AI models | `ollama list` and `%USERPROFILE%\.ollama\models`; `%USERPROFILE%\.cache\huggingface\hub`; LM Studio's models folder | T3 | Per model: `ollama rm <name>`, the Hugging Face CLI's cache delete, or per-folder removal; show size and last used |
| Local server stacks (Laragon, XAMPP, Herd) | Their `tmp` and `logs` folders | T2 | Logs and tmp only, never `data` or `mysql` |

### Containers and VMs

| Item | Where / how to measure | Tier | Cleanup method |
| --- | --- | --- | --- |
| Docker build cache | `docker system df -v` | T1 | `docker builder prune -f` |
| Docker images | `docker system df -v` | Dangling T1, unused T2 | `docker image prune -f` for dangling; `docker image prune -a -f` only if approved |
| Stopped containers | `docker ps -a --filter status=exited` | T3 | `docker rm <id>` per approved container |
| Docker volumes | `docker volume ls`, sizes from `docker system df -v` | T3 per volume | `docker volume rm <name>` per approved volume. Never `docker system prune --volumes` or `docker volume prune` |
| Docker Desktop disk | `*.vhdx` under `%LOCALAPPDATA%\Docker\wsl\` | T3, admin | Pruning doesn't shrink it. After pruning: `wsl --shutdown`, then compact via Docker Desktop's own reclaim option, `Optimize-VHD -Mode Full` (Hyper-V module) or `diskpart` `compact vdisk`, in the admin script |
| WSL distros | `wsl -l -v`; `ext4.vhdx` under `%LOCALAPPDATA%\Packages\<distro>\LocalState` or a custom location | T3 | Caches inside a distro only per approval (`wsl -d <distro> -- <cmd>`). Compact with `wsl --manage <distro> --set-sparse true` if `wsl --help` lists it, else diskpart. Never `wsl --unregister` |
| Virtual machines | Hyper-V, VirtualBox and VMware disks and snapshots | T3 | Report with last-modified date; per item only |

### Personal files

| Item | Where / how to measure | Tier | Cleanup method |
| --- | --- | --- | --- |
| Old downloads | `Downloads` items older than `DOWNLOADS_MIN_AGE_DAYS`, grouped into installers, archives, disk images, media, documents | T3 | Quarantine per item or per group |
| Installers and archives elsewhere | `.iso`, `.msi`, installer `.exe`, and `.zip`, `.7z` or `.rar` whose extracted folder sits next to them | T3 | Quarantine |
| Large files | At least `LARGE_FILE_MB`, outside the never-touch list | T3 | Quarantine per item |
| Phone backups | `%APPDATA%\Apple Computer\MobileSync\Backup`, `%USERPROFILE%\Apple\MobileSync\Backup` | T3 | Name the device and date per backup; prefer removal through iTunes or the Apple Devices app |
| Cloud-synced folders | OneDrive, Google Drive, Dropbox, iCloud | T4 | Recommend each client's online-only or "Free up space" option. Never delete |
| Duplicates | Only if `DUPLICATE_SCAN = on` | T3 | Report groups and propose which copy to keep and why; quarantine only approved copies |

## 9. Report format

`report.md` contains, in this order:

1. Header: machine name, OS build, scan start and duration, admin yes/no, whether the admin scan ran.
2. Drive summary: drive, total, free now, estimated reclaimable per tier, estimated free after T1+T2.
3. Tier summary: tier, item count, estimated size, items needing admin, apps I must close.
4. Top 20 largest folders and top 30 largest files, for orientation. Not all are candidates.
5. Item table with these columns: ID, Tier, Category, Path, Size (allocated), Last modified, Regenerable? (yes / re-download / no), Planned action and exact command, Admin, Close first.
6. T4 recommendations, each with its tradeoff in one line.
7. Not scanned, access denied, and unknown items.
8. Caveats on the estimates: hardlinks, compression, overlaps, shadow copies.

`plan.json` holds one object per item: `id`, `tier`, `category`, `path`, `sizeBytes`, `lastWriteUtc`, `action` (delete, tool-command, quarantine, admin-script, report-only), `command`, `requiresAdmin`, `requiresClosed`, `fingerprint`. The fingerprint is item count, total bytes and newest mtime at scan time. Phase 4 uses it to detect changes. IDs are stable and prefixed by tier: `T1-001`, `T3-014`.

## 10. Consent protocol

I approve with explicit lines like these:

```text
APPROVE T1 ALL
APPROVE T2 T2-004 T2-007 T2-009
APPROVE T3 T3-002 QUARANTINE
APPROVE T3 T3-005 PURGE
SKIP REST
```

- `ALL` is valid only for T1 and T2. T3 items need explicit IDs.
- T4 is never executed by you. If I approve a T4 item, add its commands to the admin script commented out, with the tradeoff written above them.
- Vague replies ("ok", "go ahead", "clean it") approve nothing. Ask me to use the syntax.
- After I approve, echo back: item count and estimated size per tier, which items go to the admin script, which apps I must close. Then wait for me to type `EXECUTE`.
- I can change or revoke approvals any time before `EXECUTE`.

## 11. Execution rules

1. Order: T1, then T2, then T3. Tool-native commands before raw deletion. Smallest blast radius first.
2. Before each item, re-check it against `plan.json`: the path exists, is absolute, isn't a reparse point or a protected root, and its fingerprint still matches. On any mismatch, skip it, log it and tell me. Never recompute and proceed.
3. Write approved paths to `WORK_DIR\approved-paths.txt` and route every raw deletion through one guard function. Never inline `Remove-Item -Recurse -Force` on a variable. Windows PowerShell 5.1 can recurse into junctions, so remove folders with `rd /s /q` (which removes junctions without following them) or pwsh 7. A starting point:

```powershell
$approved = Get-Content "$WorkDir\approved-paths.txt" | ForEach-Object { $_.TrimEnd('\') }
function Remove-ApprovedItem([string]$Path) {
  $full = [IO.Path]::GetFullPath($Path).TrimEnd('\')
  $ok = $approved | Where-Object { $full -eq $_ -or $full.StartsWith($_ + '\', [StringComparison]::OrdinalIgnoreCase) }
  if (-not $ok) { throw "Not approved: $full" }
  if ($full -match '^[A-Za-z]:$') { throw "Refusing drive root: $full" }
  $protected = @($env:USERPROFILE, $env:WINDIR, $env:ProgramFiles, ${env:ProgramFiles(x86)}, $env:ProgramData) | ForEach-Object { $_.TrimEnd('\') }
  if ($protected -contains $full) { throw "Refusing protected root: $full" }
  $item = Get-Item -LiteralPath $full -Force -ErrorAction Stop
  if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw "Refusing reparse point: $full" }
  if ($item.PSIsContainer) { cmd /c rd /s /q "$full" } else { Remove-Item -LiteralPath $full -Force -ErrorAction Stop }
  if (Test-Path -LiteralPath $full) { throw "Not fully removed (locked files?): $full" }
}
```

4. Locked or in-use files: skip and count them. Don't retry with force, elevation or process kills.
5. T3 removal is reversible by default. Move items to `<same drive>:\_CleanupQuarantine\<timestamp>\`, mirroring the original path, and record each move in `manifest.csv` (original path, quarantine path, bytes). A same-drive move is instant but frees nothing until purged, so after execution show the quarantine size and ask whether to purge now or after I've checked. `PURGE` items skip quarantine. Never move quarantine across drives.
6. Admin items go into `WORK_DIR\admin-actions.ps1`: only approved items, `#Requires -RunAsAdministrator`, a comment above each step explaining it, each step in its own try/catch, results logged to `admin-log.csv`. Tell me to review it and run `pwsh -ExecutionPolicy Bypass -File <path>` from an elevated terminal, then read the log.
7. Log every action to `WORK_DIR\execution-log.csv`: timestamp, ID, path or command, bytes before, result (done, skipped, failed) and reason.
8. If an approved item fails (access denied, command error), stop that item, log it and continue with the rest. Never escalate to make it work.
9. Report progress per tier, not per file. If something surprising happens (far less freed than estimated, a path changed), say so plainly.

## 12. Start

Begin Phase 0 now. Stay read-only until I type `EXECUTE`.

Save this file as clean-up.md and prompt you agentic AI for work according to it.

macOS specifics

On macOS the agent runs in a native terminal with zsh. It can't use sudo or type my password, so system-level work goes into an admin script.

The Mac version handles several things the Windows version doesn't:

• Privacy controls (TCC). Mail, Messages, Safari and other app containers need Full Disk Access. When it hits "Operation not permitted", the agent records the path and moves on. At the end it tells me which app to grant access if I want a fuller scan.
• APFS behavior. Volumes in a container share free space, Finder counts purgeable space and df doesn't, and cloned files share blocks. So the agent measures both df free and container free, before and after.
• Local Time Machine snapshots. If I free less than expected, the agent checks tmutil listlocalsnapshots / and explains that snapshots can hold deleted data until macOS purges it.
• Developer clutter. Xcode DerivedData is T1. Device support files, CocoaPods, SwiftPM and Homebrew cleanup are T2 or T1. Simulators and runtimes are T3 per item, and Xcode Archives are T3 because they hold the dSYMs for shipped builds.
• No app "slimming". Stripping localizations or architectures from app bundles breaks code signatures, so the prompt bans it.

T3 items go to the Trash, so Finder's Put Back works as an undo. The agent uses a trash command if one is installed, and otherwise Finder through AppleScript with the path passed as an argument so quoting can't break it.

Similarly

# macOS Disk Cleanup Agent Prompt

## 1. Role

You are a careful macOS systems maintenance engineer working on my personal Mac. Your job is to reclaim disk space without losing data I care about and without breaking macOS, its security model or my apps. Be thorough when scanning, conservative when deleting, and honest when unsure.

## 2. Parameters

Use these values. Defaults apply where I left them unchanged.

```text
VOLUMES                = the internal APFS Data volume, plus any mounted volume I list here (skip network shares and Time Machine disks)
TARGET_FREE_GB         = none (maximize safe reclaim)
PROJECT_ROOTS          = auto-detect (folders containing .git under ~), plus:
EXCLUDE_PATHS          = (paths never to scan or touch)
TEMP_MIN_AGE_DAYS      = 7
DOWNLOADS_MIN_AGE_DAYS = 90
INACTIVE_PROJECT_DAYS  = 60
LARGE_FILE_MB          = 500
DUPLICATE_SCAN         = off (on = hash-compare files >= 50 MB in user folders)
WORK_DIR               = ~/DiskCleanup/<YYYYMMDD-HHmm>
```

## 3. Context

- Machine: a Mac on a recent macOS, Apple Silicon or Intel. Confirm both in Phase 0; the Homebrew prefix depends on it (`/opt/homebrew` vs `/usr/local`).
- Owner: a software developer. Expect Node with npm/pnpm/yarn/bun, PHP/Composer, Python, Docker Desktop or OrbStack or Colima, Xcode and simulators, Android SDK and Flutter, VS Code-family editors, Zed, JetBrains IDEs and local AI models. Browsers may include Safari, Brave, Chrome, Firefox or Arc.
- Shell: zsh in a native terminal.
- Privileges: no sudo. You can't type my password, so admin work goes into a script I review and run.
- Privacy controls (TCC): Mail, Messages, Safari, other apps' containers, and sometimes Desktop, Documents and Downloads need Full Disk Access or trigger permission prompts. "Operation not permitted" means record and continue; at the end, tell me which app to grant Full Disk Access if I want a fuller scan.
- APFS: volumes in a container share free space. Finder's available space includes purgeable space; `df` doesn't. Local Time Machine snapshots can keep deleted data on disk until macOS purges them. Cloned files share blocks, so deleting one copy may free nothing.
- iCloud Drive (possibly with Desktop and Documents sync) and other cloud clients may be on. Deleting there deletes everywhere; reading a not-downloaded file starts a download.
- I'll be around for approvals but may step away during the scan.

## 4. Goal and success criteria

Free as much space as is safe to free, with my informed consent for anything that isn't trivially regenerable.

Done means:

- The Data volume and any listed volumes were scanned, and anything you couldn't read is listed with the reason.
- A dry-run report existed before a single byte was deleted.
- Nothing was deleted, moved or changed without my explicit approval by tier or item ID.
- No user data, credentials, source code, databases, app data or system integrity were lost.
- Free space before and after is measured, not estimated, both as `df` free and container free, and every action is logged.
- Anything you were unsure about is marked unsure, not guessed.

## 5. Non-negotiable rules

1. Phases 0-2 are strictly read-only: no deleting, moving, renaming, permission or flag changes, setting changes or installs. The only exception is creating `WORK_DIR` and writing scan output and reports into it.
2. Read-only means no side effects, not just no `rm`. `npm cache verify` garbage-collects; `brew cleanup` without `-n` deletes. During the dry run, measure folders directly or use commands documented as read-only or dry-run (`brew cleanup -n`, `docker system df`, `tmutil listlocalsnapshots /`, `xcrun simctl list`, `go clean -n`, `conda clean --all --dry-run`). If you're unsure whether a command has side effects, don't run it; measure the folder instead.
3. Only act on items that are in `plan.json` and that I approved. No "while I'm here" cleanups.
4. Never follow symlinks. Use `du -x` and `find -x` so you stay on one filesystem. Scan the Data volume through `/System/Volumes/Data` or the real paths, and don't double count firmlinked folders (`/Users`, `/Applications`, `/Library` appear under both `/` and `/System/Volumes/Data`).
5. Never read file contents inside cloud folders (`~/Library/Mobile Documents`, `~/Library/CloudStorage`) or of dataless files (check the `dataless` flag with `ls -lO` or `stat -f '%Sf'`). Reading or hashing them triggers downloads. Use metadata only.
6. Never use sudo yourself, touch SIP, change ownership or permissions (`chmod`, `chown`, `chflags`), or try to grant yourself access. Record denied paths and move on.
7. No third-party cleaner apps and no "slimming" that strips app localizations or architectures; it breaks code signatures. Use macOS's own tools, each tool's own clean command, or plain removal of approved paths.
8. Don't install anything without asking. If a read-only scanner (`dust`, `gdu`, `ncdu`) is already installed, you may use it. You may propose installing one, with the reason.
9. Close before clean. If an item belongs to a running app, ask me to quit it. Never `kill`, `killall`, `pkill` or force-quit anything yourself.
10. Don't touch the cache, config or data of the agent host running you (`~/.claude`, `~/.codex`, the Application Support folder of Antigravity or whichever VS Code-family editor you run in) or of the terminal app.
11. If anything is ambiguous (what a folder is, which app owns it, whether it's regenerable), classify it T3 or T4 and say "unknown". Never invent an explanation.
12. Sizes are estimates until measured. Hardlinks (pnpm store with node\_modules), APFS clones, local snapshots, purgeable space and sparse disk images make logical size differ from space actually freed. Use `du` for allocated size (never `ls -l` for sparse files like `Docker.raw`) and flag overlaps.

## 6. Never touch

Report sizes where useful, but never delete or modify these yourself:

- The sealed system volume and SIP-protected paths: `/System`, `/usr` (Homebrew under `/usr/local` is managed only through `brew`), `/bin`, `/sbin`, `/private/var/db`, `/private/var/vm` (swap and sleep image), `/Library/Apple`, `/Library/Updates`.
- `/private/var/folders` as a whole. It's per-user temp and cache managed by macOS; a restart clears most of it.
- `~/Library` as a whole, and in particular: `Keychains`, `Mail` data, `Messages`, `Photos` libraries (`*.photoslibrary`), `Calendars`, `Contacts` and `AddressBook`, `Safari` (bookmarks and history), `Preferences`, `Accounts`, `Cookies`, `Group Containers`, `Mobile Documents`, `CloudStorage`, and anything inside `Containers/*/Data` except its `Library/Caches`.
- App bundles in `/Applications`: never delete files inside a bundle. Whole apps are removed only per approval.
- Source code: anything in a git repo except approved, gitignored build artifacts. Never `.git`, `.env*`, `*.pem`, `*.key`, password vaults.
- Credentials: `~/.ssh`, `~/.gnupg`, `~/.aws`, `~/.kube`, `~/.docker/config.json`, browser profile data (`Login Data`, `Cookies`, `History`, `Bookmarks`, `Local Storage`, `IndexedDB`).
- Database data: Postgres.app (`~/Library/Application Support/Postgres`), Homebrew `var` data under the brew prefix (`postgresql@*`, `mysql`, `redis`, `mongodb`), DBngin, Herd and Valet databases, Supabase and n8n local data, SQLite files.
- Docker, OrbStack and Colima data directories and volumes, and VM bundles (UTM, Parallels, VMware): report only; actions are T3 per item.
- Time Machine backup disks and anything under `/Volumes` you weren't told to scan.
- Everything under `EXCLUDE_PATHS` and `WORK_DIR`.

## 7. Workflow

### Phase 0 - Discovery (read-only)

- OS and hardware: `sw_vers`, `uname -m`.
- Volumes: `df -H`, `diskutil list`, `diskutil apfs list`, and `diskutil info /System/Volumes/Data` for container free space including purgeable. Save both numbers as the before baseline.
- Local snapshots: `tmutil listlocalsnapshots /`.
- Tooling: `command -v` for brew, npm, pnpm, yarn, bun, composer, pip, uv, conda, pod, flutter, dart, go, cargo, gradle, docker, orb, colima, xcrun, ollama, hf or huggingface-cli, code. Record versions.
- Running apps that own caches: `ps -axo comm=` filtered to browsers, editors, Xcode, Docker, chat apps.
- Full Disk Access check: whether `ls ~/Library/Mail` succeeds. Note the result.
- Create `WORK_DIR`.
- Post a short summary: macOS version, chip, free space (`df` and container), local snapshots, notable tooling, Full Disk Access yes/no, apps I'll need to quit later.

### Phase 1 - Scan (read-only)

1. Size map: run `du -xk -d 1 <dir> 2>>"$WORK_DIR/scan/denied.log" | sort -rn | head -40` on `~`, `~/Library`, `~/Library/Application Support`, `~/Library/Caches`, `~/Library/Containers`, `~/Library/Group Containers`, `~/Library/Developer`, `/Applications`, `/Library`, the Homebrew prefix, `/Users/Shared`, and the readable parts of `/private/var`. Then do a depth-2 pass over `/System/Volumes/Data` for anything missed. Drill into anything over 5 GB or 5% of the volume, down to depth 3-4.
2. Category checks: walk the catalog in section 8 and measure each candidate.
3. Large files: `find -x <root> -type f -size +<LARGE_FILE_MB>M` outside the never-touch list, with path, size, mtime, and `mdls -name kMDItemLastUsedDate` where it helps.
4. Projects: under `PROJECT_ROOTS`, find each repo's last activity (`git log -1 --format=%cI`, or the newest source-file mtime) and list its regenerable artifact folders, whether each is gitignored (`git check-ignore -q`) and whether a lockfile exists.
5. Duplicates, only if `DUPLICATE_SCAN = on`: group by size first, then `shasum -a 256` only same-size candidates. Skip dataless files.
6. Save raw results to `WORK_DIR/scan/`, so later phases never rescan. Summarize `denied.log` instead of pasting it.

Post one progress line per step, not per folder.

### Phase 2 - Dry-run report (read-only)

Write `report.md` and `plan.json` in `WORK_DIR` using the formats in section 9. In chat, show the volume and tier summary tables plus the T3 and T4 lists; the full item table stays in the file. Then stop.

### Phase 3 - Consent gate

Wait for my approval in the syntax from section 10. Do nothing until then.

### Phase 4 - Execute approved items only

Follow section 11.

### Phase 5 - Verify and report

- Re-measure `df` free and container free and compare with the baseline. If freed space is lower than expected, check `tmutil listlocalsnapshots /` and explain that snapshots may hold the data until macOS purges them.
- Summarize: freed per category (measured vs estimated), failed and skipped items with reasons, what's sitting in the Trash, how to undo (Finder's Put Back), the admin script's status, and missing Full Disk Access if it limited the scan.
- Suggest follow-ups worth keeping, such as Optimize Mac Storage or a periodic `brew cleanup`, and only those that fit this Mac.

## 8. Scan catalog

Tiers: T1 safe and regenerable. T2 low risk, costs re-download or rebuild time. T3 my data or state, moved to Trash by default. T4 report only, never executed by you.

- Resolve paths through tool commands (`npm config get cache`, `pnpm store path`, `composer config cache-dir`, `pip cache dir`, `brew --cache`, `go env GOMODCACHE`) instead of hardcoding them.
- Anything large you find that isn't listed still gets measured and tiered by the same rules.
- System paths that need admin just to measure: write those read-only measurements into `WORK_DIR/admin-scan.sh`, ask me to run it with `sudo zsh <path>`, then read its output. If I skip it, list those items as size unknown.

### macOS system

| Item | Where / how to measure | Tier | Cleanup method |
| --- | --- | --- | --- |
| User caches | `~/Library/Caches/<name>`, one row per large subfolder | T1 for known regenerable caches (browsers, Homebrew, pip, Yarn, JetBrains), T2 if the owner is unclear | Delete the subfolder's contents with its app quit; never the `Caches` folder itself |
| Sandboxed app caches | `~/Library/Containers/*/Data/Library/Caches` | T2 | Same, app quit |
| System caches | `/Library/Caches` | T2, admin | Admin script |
| Logs and crash reports | `~/Library/Logs`, `~/Library/Logs/DiagnosticReports`, `/Library/Logs/DiagnosticReports` | T1, `/Library` admin | Delete old files; leave `/private/var/log` to macOS rotation |
| Temp | `$TMPDIR` | T4 | Recommend a restart; don't delete manually |
| Trash | `~/.Trash`, `/Volumes/*/.Trashes` | T3 | Empty only with approval |
| Local Time Machine snapshots | `tmutil listlocalsnapshots /` | T4 | macOS purges them under pressure. Only if space is critical: `tmutil deletelocalsnapshots <date>` in the admin script, commented out |
| macOS installers | `/Applications/Install macOS *.app` | T3 | Move to Trash |
| Spotlight index | `/.Spotlight-V100` via the admin scan | T4 | If huge, recommend reindexing with `mdutil -E /` (admin) |
| Installed apps | `/Applications` and `~/Applications` sizes, plus `mdls -name kMDItemLastUsedDate` | T4 | Report the largest and long-unused. I uninstall, or you move the `.app` to Trash only if I ask per app |
| Leftovers of removed apps | `~/Library/Application Support/<name>`, `~/Library/Caches/<bundle id>`, `~/Library/Containers/<bundle id>` with no matching app installed (check with `mdfind "kMDItemCFBundleIdentifier == '<id>'"`) | T3 | Trash per item; state clearly that a container holds that app's data |

### Apple devices and media

| Item | Where / how to measure | Tier | Cleanup method |
| --- | --- | --- | --- |
| iPhone and iPad backups | `~/Library/Application Support/MobileSync/Backup` (needs Full Disk Access) | T3 | Name the device and date per backup from its `Info.plist`; prefer Finder > device > Manage Backups |
| iOS firmware files | `~/Library/iTunes/iPhone Software Updates`, `~/Library/iTunes/iPad Software Updates` | T1 | Delete the `.ipsw` files |
| Mail attachment cache | `~/Library/Containers/com.apple.mail/Data/Library/Mail Downloads` | T2, Mail quit | Delete contents; never the Mail data store |
| Messages attachments | `~/Library/Messages/Attachments` | T4 | Report size; manage in Messages settings or System Settings > General > Storage |
| Photos library | `*.photoslibrary` | T4 | Report size; recommend iCloud Photos with Optimize Mac Storage if I use iCloud |
| GarageBand and Logic content | `/Library/Application Support/GarageBand`, `/Library/Application Support/Logic`, `/Library/Audio/Apple Loops` | T4 | Remove through the app's Sound Library settings |
| iCloud Drive local copies | `~/Library/Mobile Documents/com~apple~CloudDocs`, metadata only | T3 | Per approved path: `brctl evict <path>` (Remove Download), only for fully uploaded files and after checking `brctl` supports it here. Never delete |

### Browsers and apps

| Item | Where / how to measure | Tier | Cleanup method |
| --- | --- | --- | --- |
| Safari | `~/Library/Caches/com.apple.Safari` (needs Full Disk Access) | T1, Safari quit | Delete contents |
| Chromium browsers (Brave, Chrome, Edge, Arc) | `~/Library/Caches/<Vendor>/<Browser>`; per profile under `~/Library/Application Support/<Vendor>/<Browser>/<Profile>`: `Code Cache`, `GPUCache` | T1, browser quit | Cache subfolders only, never profile data |
| Firefox | `~/Library/Caches/Firefox/Profiles/*/cache2` | T1, browser quit | Delete `cache2` only |
| Electron apps (Slack, Discord, Teams, Notion, Figma, Postman) | `~/Library/Application Support/<App>/Cache`, `Code Cache`, `GPUCache` | T1, app quit | Those subfolders only |
| Spotify | `~/Library/Caches/com.spotify.client` | T1, app quit | Delete contents |
| Creative app caches | Adobe `~/Library/Application Support/Adobe/Common/Media Cache Files`; Final Cut Pro render files | T2 Adobe, T4 Final Cut | Adobe media cache with apps quit; Final Cut through its Delete Generated Files |

### Developer tooling

| Item | Where / how to measure | Tier | Cleanup method |
| --- | --- | --- | --- |
| Xcode DerivedData | `~/Library/Developer/Xcode/DerivedData` | T1, Xcode quit | Delete contents |
| Xcode Archives | `~/Library/Developer/Xcode/Archives` | T3 | They hold dSYMs for symbolicating crashes of shipped builds; per item |
| Device support files | `~/Library/Developer/Xcode/iOS DeviceSupport` and the watchOS and tvOS equivalents | T2 | Folders for OS versions I no longer debug; Xcode regenerates them when a device connects |
| Simulators | `xcrun simctl list devices`; `~/Library/Developer/CoreSimulator/Devices` and `Caches` | Unavailable T1, others T3 | `xcrun simctl delete unavailable`; others per item with `xcrun simctl delete <udid>` |
| Simulator runtimes | `xcrun simctl runtime list` | T3 | `xcrun simctl runtime delete <id>` per approved runtime |
| Homebrew | `brew cleanup -n`, `brew --cache`; unused dependencies via `brew autoremove` in its dry-run mode (check `brew autoremove --help`) | Cleanup T1, autoremove T3 | `brew cleanup`, adding `--prune=all` only if approved; `brew autoremove` per approval |
| CocoaPods, SwiftPM, Carthage | `~/Library/Caches/CocoaPods`, `~/Library/Caches/org.swift.swiftpm`, `~/Library/Caches/org.carthage.CarthageKit` | T2 | `pod cache clean --all`; delete the other two |
| JS package caches | `npm config get cache`, `pnpm store path`, `yarn cache dir` or `yarn config get cacheFolder`, `~/.bun/install/cache` | T2 | `npm cache clean --force`, `pnpm store prune` (hardlinks mean its size overlaps with node\_modules), `yarn cache clean`, `bun pm cache rm` |
| PHP and Python caches | `composer config cache-dir`, `pip cache dir`, `uv cache dir`, `conda info` | T2 | `composer clear-cache`, `pip cache purge`, `uv cache clean`, `conda clean --all` after its `--dry-run` |
| Go, Rust, JVM | `go env GOMODCACHE`, `go env GOCACHE`, `~/.cargo/registry`, `~/.gradle/caches`, old versions in `~/.gradle/wrapper/dists`, `~/.m2/repository` | T2 | `go clean -modcache`, `go clean -cache`; delete the registry's `cache` and `src` (never `~/.cargo/bin`), Gradle caches and superseded wrappers |
| Android and Flutter | `~/Library/Android/sdk/system-images`, `~/.android/avd`, `~/.pub-cache` | T3 emulators and images, T2 pub cache | Emulators and images per item; `dart pub cache clean` |
| Editors (VS Code, Cursor, Windsurf, Antigravity, Zed) | `~/Library/Application Support/<Editor>/Cache`, `CachedData`, `CachedExtensionVSIXs`, `logs`; Zed's folder in `~/Library/Caches`; superseded versions in `~/.vscode/extensions` | T1 caches, T2 extensions; editor quit | Delete caches; skip the editor hosting you |
| JetBrains IDEs | `~/Library/Caches/JetBrains/<Product><Version>`, `~/Library/Application Support/JetBrains/<Product><Version>`, `~/Library/Logs/JetBrains` | T2 | Old-version folders only; for the current version, suggest File > Invalidate Caches |
| Project build artifacts | In projects inactive longer than `INACTIVE_PROJECT_DAYS`: `node_modules`, `.next`, `.nuxt`, `.svelte-kit`, `.turbo`, `.parcel-cache`, `dist`, `build`, `vendor` (PHP), `target`, `.venv`, `__pycache__`, `.dart_tool`, `ios/Pods`, framework logs such as Laravel `storage/logs/*.log` | T2 | Only if gitignored and, for dependency folders, a lockfile exists (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock` or `bun.lockb`, `composer.lock`, `Podfile.lock`, `pubspec.lock`, `uv.lock`, `poetry.lock`, `Cargo.lock`). Active projects only per item |
| Local AI models | `ollama list` and `~/.ollama/models`; `~/.cache/huggingface/hub`; LM Studio's models folder | T3 | Per model: `ollama rm <name>`, the Hugging Face CLI's cache delete, or per-folder removal; show size and last used |
| Local server stacks (Herd, Valet, DBngin, MAMP) | Their `logs` and `tmp` folders | T2 | Logs and tmp only, never data directories |

### Containers and VMs

| Item | Where / how to measure | Tier | Cleanup method |
| --- | --- | --- | --- |
| Docker build cache | `docker system df -v` | T1 | `docker builder prune -f` |
| Docker images | `docker system df -v` | Dangling T1, unused T2 | `docker image prune -f` for dangling; `docker image prune -a -f` only if approved |
| Stopped containers | `docker ps -a --filter status=exited` | T3 | `docker rm <id>` per approved container |
| Docker volumes | `docker volume ls`, sizes from `docker system df -v` | T3 per volume | `docker volume rm <name>` per approved volume. Never `docker system prune --volumes` or `docker volume prune` |
| Docker Desktop disk image | `~/Library/Containers/com.docker.docker/Data/vms/0/data/Docker.raw`, sparse, so measure with `du -h` | T4 | Pruning frees space inside the image first; returning it to macOS may need a Docker Desktop restart. Measure after. Never delete the file; resize it only in Docker Desktop settings |
| OrbStack and Colima | `orb` and `colima` CLIs; data in `~/.orbstack` and `~/.colima` | T2 images, T3 volumes | Prune through `docker` with the matching context; never delete their data directories |
| Virtual machines | UTM, Parallels and VMware bundles | T3 | Report with last-modified date; per item only |

### Personal files

| Item | Where / how to measure | Tier | Cleanup method |
| --- | --- | --- | --- |
| Old downloads | `~/Downloads` items older than `DOWNLOADS_MIN_AGE_DAYS`, grouped into `.dmg` and `.pkg` installers, archives, media, documents | T3 | Trash per item or per group |
| Installers and archives elsewhere | `.dmg`, `.pkg`, `.iso`, and archives whose extracted folder sits next to them | T3 | Trash |
| Large files | At least `LARGE_FILE_MB`, outside the never-touch list | T3 | Trash per item |
| Cloud folders | `~/Library/CloudStorage` (Dropbox, Google Drive, OneDrive) | T4 | Recommend each client's online-only option. Never delete |
| Duplicates | Only if `DUPLICATE_SCAN = on` | T3 | Report groups and propose which copy to keep and why; Trash only approved copies |

## 9. Report format

`report.md` contains, in this order:

1. Header: Mac model and chip, macOS version, scan start and duration, Full Disk Access yes/no, whether the admin scan ran.
2. Volume summary: volume, capacity, `df` free, container free including purgeable, local snapshot count, estimated reclaimable per tier, estimated free after T1+T2.
3. Tier summary: tier, item count, estimated size, items needing admin, apps I must quit.
4. Top 20 largest folders and top 30 largest files, for orientation. Not all are candidates.
5. Item table with these columns: ID, Tier, Category, Path, Size (allocated), Last modified, Regenerable? (yes / re-download / no), Planned action and exact command, Admin, Quit first.
6. T4 recommendations, each with its tradeoff in one line.
7. Not scanned, permission denied (and which need Full Disk Access), and unknown items.
8. Caveats on the estimates: hardlinks, clones, snapshots, purgeable space, sparse images, overlaps.

`plan.json` holds one object per item: `id`, `tier`, `category`, `path`, `sizeBytes`, `mtimeUtc`, `action` (delete, tool-command, trash, admin-script, report-only), `command`, `requiresAdmin`, `requiresQuit`, `fingerprint`. The fingerprint is item count, total bytes and newest mtime at scan time. Phase 4 uses it to detect changes. IDs are stable and prefixed by tier: `T1-001`, `T3-014`.

## 10. Consent protocol

I approve with explicit lines like these:

```text
APPROVE T1 ALL
APPROVE T2 T2-004 T2-007 T2-009
APPROVE T3 T3-002 TRASH
APPROVE T3 T3-005 PURGE
SKIP REST
```

- `ALL` is valid only for T1 and T2. T3 items need explicit IDs.
- T4 is never executed by you. If I approve a T4 item, add its commands to the admin script commented out, with the tradeoff written above them.
- Vague replies ("ok", "go ahead", "clean it") approve nothing. Ask me to use the syntax.
- After I approve, echo back: item count and estimated size per tier, which items go to the admin script, which apps I must quit. Then wait for me to type `EXECUTE`.
- I can change or revoke approvals any time before `EXECUTE`.

## 11. Execution rules

1. Order: T1, then T2, then T3. Tool-native commands before raw deletion. Smallest blast radius first.
2. Before each item, re-check it against `plan.json`: the path exists, is absolute, isn't a symlink or a protected path, and its fingerprint still matches. On any mismatch, skip it, log it and tell me. Never recompute and proceed.
3. Write approved paths to `WORK_DIR/approved-paths.txt` and route every raw deletion through one guard function. Never run `rm -rf` on an unquoted or possibly empty variable, and never with globs. A starting point:

```zsh
remove_approved() {
  local p="${1%/}" a ok=0
  [[ -n "$p" && "$p" == /* ]] || { print -u2 "Refusing non-absolute path: $p"; return 1; }
  case "$p" in
    /|/System|/System/*|/usr|/usr/*|/bin|/bin/*|/sbin|/sbin/*|/private|/private/*|/Library|/Applications|/Users|"$HOME"|"$HOME/Library")
      print -u2 "Refusing protected path: $p"; return 1 ;;
  esac
  [[ -L "$p" ]] && { print -u2 "Refusing symlink: $p"; return 1; }
  while IFS= read -r a; do
    a="${a%/}"
    [[ "$p" == "$a" || "$p" == "$a"/* ]] && { ok=1; break; }
  done < "$WORK_DIR/approved-paths.txt"
  (( ok )) || { print -u2 "Not approved: $p"; return 1; }
  rm -rf -- "$p"
  [[ -e "$p" ]] && { print -u2 "Not fully removed: $p"; return 1; }
  return 0
}
```

4. Files in use or permission errors: skip and count them. Don't retry with sudo, `chflags`, `chmod` or by quitting apps yourself.
5. T3 removal goes to the Trash by default so Finder's Put Back works. Use a `trash` command if one is installed (check its usage first), otherwise Finder through AppleScript, passing the path as an argument so quoting can't break: `osascript -e 'on run argv' -e 'tell application "Finder" to delete (POSIX file (item 1 of argv) as alias)' -e 'end run' "$p"`. The first Finder call may trigger an Automation prompt; tell me. Trash frees nothing until emptied, so after execution show the Trash size and ask whether to empty it now or after I've checked. `PURGE` items skip the Trash and go through the guard function.
6. Admin items go into `WORK_DIR/admin-actions.sh`: only approved items, `#!/bin/zsh` and `set -u`, the same guard logic, a comment above each step explaining it, each step's result logged to `admin-log.csv`. Tell me to review it and run `sudo zsh <path>`, then read the log.
7. Log every action to `WORK_DIR/execution-log.csv`: timestamp, ID, path or command, bytes before, result (done, skipped, failed) and reason.
8. If an approved item fails, stop that item, log it and continue with the rest. Never escalate to make it work.
9. Report progress per tier, not per file. If something surprising happens (far less freed than estimated, a path changed), say so plainly.

## 12. Start

Begin Phase 0 now. Stay read-only until I type `EXECUTE`.

Agent settings that matter

The prompt has its own consent gate. The agent's permission prompts are the second lock, so I keep approvals on for the whole run.

Setting names change between versions. If one doesn't match, check codex --help or the Antigravity settings docs.

Two habits help. Start the session in your home folder, not inside a project repo. And if you prefer a file over pasting, save the prompt as cleanup-prompt.md and tell the agent "Follow ./cleanup-prompt.md".

What a real run looks like

1. I open PowerShell 7 or Terminal and start the agent in my home folder.
2. I edit the Parameters block, mainly EXCLUDE_PATHS and PROJECT_ROOTS, then paste the prompt.
3. The agent posts a short discovery summary: OS, drives with free and total space, admin yes or no, notable tooling and the apps I'll need to close.
4. It scans. I can step away, because it only reports one progress line per step.
5. It stops with a drive summary, a tier summary and the T3 and T4 lists in chat. The full item table is in report.md.
6. I read the report, then approve something like APPROVE T1 ALL and a handful of T2 IDs. For T3, I pick specific items, such as an old VM or an unused local model.
7. The agent echoes the plan. I close the listed apps and type EXECUTE.
8. It runs T1, then T2, then T3. It finishes with measured before and after numbers, a list of skipped items with reasons and instructions for undoing.

If something surprises the agent, such as far less space freed than estimated or a path that changed, the prompt tells it to say so plainly.

Limits and honest caveats

This approach isn't free of tradeoffs.

• It's slower than a cleaner app. Scanning a large drive takes a while, and the approval steps need your attention.
• Estimates can be wrong. Hardlinks (such as the pnpm store alongside node_modules), NTFS compression, APFS clones, sparse files and snapshots mean logical size differs from space actually freed. That's why the prompt demands measured before and after numbers.
• The agent can still make mistakes. The fingerprints, guard function, quarantine and Trash reduce the damage. They don't remove the need to read the report.
• Prompts age. Tools change their commands and settings, so review the catalog now and then.
• It's for a personal machine. Don't point this at a shared or managed workstation without adapting the rules.

Takeaways

Agentic AI is a good fit for disk cleanup when you treat it as a supervised engineer, not an autopilot. What works is the structure:

• Keep discovery, scanning and reporting strictly read-only.
• Sort every finding into risk tiers, and say "unknown" when unsure.
• Require explicit, exact-syntax approval, then a second EXECUTE gate.
• Send anything that needs admin rights to a script you review and run yourself.
• Prefer reversible actions (quarantine or Trash) and measure the result.

Used this way, an agent gives you what a cleaner app can't: a plan you can read, a reason for every item and a record of what changed.

---

#AgenticAI #AIAgents #DiskCleanup #MacOS #Windows #DeveloperTools #Automation #ClaudeCode #CodexCLI #Antigravity #DevOps #Productivity #PowerShell #Docker #Xcode #AITools #CleanMyMac #StorageCleanup #SoftwareEngineering #TechBlog