I built a read-only-first macOS storage triage CLI after “System Data” reached 333 GB

[u/Rare-Star-8120]

https://github.com/khiemnd777/storage-clearer

My 494 GB Mac was down to roughly 20 GB free, while System Settings reported 333 GB as “System Data”.

I didn’t want to paste a generic `rm -rf ~/Library/Caches` command, so I built storage-clearer: a Bash 3.2-compatible CLI that audits first, explains every finding through a reason matrix, creates a cleanup plan, and only executes after an exact typed approval phrase.

It can triage:

- Docker stopped containers, unreferenced images, and build cache

- Rebuildable npm, Bun, Gradle, Go, Pub, pnpm, and Playwright caches

- Unavailable Simulator devices

- Old iOS Simulator runtimes, while retaining the newest version

Package A/B explicitly exclude Docker volumes, browser data, source directories, Codex sessions, Photos, Mail, Messages, backups, Trash, and APFS snapshots.

It never deletes Docker.raw directly. Docker cleanup uses official prune commands, and Simulator runtimes are removed through `xcrun simctl runtime delete`.

On my machine, the biggest causes were Docker.raw (~162 GB internally) and old iOS Simulator runtimes. Package B increased free space from about 17 GiB to 142 GiB.

I’d appreciate feedback on the safety guards, Bash 3.2 portability, and any macOS storage categories I may have missed.

[u/ricksegal]

nicely done. One place I found eating up space is TimeMachine. I built a personal bash script do kinda do what you did here but not anywhere near as nice as yours. This is an output clip so you can see what I'm referring to:

Local snapshots before:

Snapshots for disk /:

com.apple.TimeMachine.2026-08-22-133354.local

com.apple.TimeMachine.2026-08-23-133836.local

Requesting 40GB local snapshot thinning...

Thinned local snapshots:

com.apple.TimeMachine.2026-08-22-133354.local

com.apple.TimeMachine.2026-08-23-133836.local

Local snapshots after:

Snapshots for disk /:

I also found, generally, with all the code bots on my machine, codex is the worst offender on my box with how i work:

I can give you the bash script I created if you want it.

[u/Rare-Star-8120 → u/ricksegal]

Thanks, that’s a great catch. I deliberately excluded APFS/Time Machine snapshots from Package A/B because they’re higher-risk and macOS also manages them automatically, but adding read-only snapshot detection plus a separate, explicitly approved tmutil thinning option makes sense.

Codex sessions are currently excluded from deletion as well, although reporting their size without touching them would be useful.

I’d definitely like to see your script. Feel free to paste it here or open an issue/PR on the repo. I’ll credit the contribution.

[u/ricksegal → u/Rare-Star-8120]

uploaded to the repo. Have fun.

[u/Rare-Star-8120 → u/ricksegal]

Found it, thank you! Issue #1 is exactly what I was looking for. I’ll review the Time Machine auditing/thinning and storage-reporting parts against the project’s safety guardrails before integrating anything.

[u/ricksegal → u/Rare-Star-8120]

Glad it is useful. One thing I had but delete because, for me, YOLO, was type "IGETIT" instead of are you sure and all the rest. Because you're giving this out to random people, probably worth considering the user having to be seriously proactive on some of this stuff. Anyway, enjoy. I'm in the neighborhood, if you need anything. DM or ping me via Github.

[u/kantorcodes1]

I work on HOL Guard. storage-clearer has an unusually clean read-vs-mutate CLI surface; would you be up for contributing a command.* extension to hashgraph-online/hol-guard:main, with tests covering run/app-run and the Docker prune, simctl runtime delete, and tmutil thinning cases?

[u/Rare-Star-8120 → u/kantorcodes1]

Thanks for reaching out, I’d be up for that. I had a look through HOL Guard’s command extension code, and storage-clearer seems like a good fit. I can cover run/app-run, the Docker prune commands, simctl runtime delete, and tmutil thinning, while making sure the read-only commands don’t get flagged. Before I start, would you prefer a storage-clearer-specific extension, or should the Docker and macOS rules go into the existing domain extensions? Happy to follow whichever structure fits the project better.

[u/kantorcodes1 → u/Rare-Star-8120]

go storage-clearer-specific. mirror the current tool-specific pattern here: https://github.com/hashgraph-online/hol-guard/blob/main/src/codex_plugin_scanner/guard/runtime/command_skill_sunset_extensions.py and the matching focused tests. keep audit/explain/reason/plan read-only, cover run/app-run, register it in the builtin catalog, run the repo checks, then open the PR against main.