I Built My Own macOS Disk Cleaner

By Andrei Roman

It got me 235 GB back in one weekend.

It deleted nothing important. That's the trick.

Every macOS disk cleaner I tried answered the wrong question

My MacBook told two users two different free-space numbers. My account: 124 GB. The other account on the same machine: closer to 500. Same disk, same day.

Storage Settings couldn't explain it. Finder disagreed with both. The commercial disk cleaner apps wanted to delete my caches and call it a day.

Twenty years in safety-critical software taught me one reflex: when a system reports two values for one physical quantity, you need a new instrument.

Why Storage Settings can't tell you the truth

Apple's storage view is instant because it never looks at your disk. Spotlight and a daemon called CacheDelete maintain running totals - a ledger, updated for months in the background. Open Storage Settings and you're reading their bookkeeping.

Ledgers inherit the politics of the bookkeeper. macOS has a category called purgeable - snapshots, re-downloadable files, certain caches - that some views count as free and others as used. That's how one disk carries two truths, and why no built-in view could show me where 389 GB of "reclaimable" actually lived.

The only audit for a ledger is a census. So I built the census, as a map.

Terrazzo: a macOS disk cleaner that shows instead of deletes

A treemap of your whole disk - the finviz-heatmap look: every folder a rectangle sized by its real allocated bytes, children tiling their parent, each level dimmer. Zoom into any rectangle. Zoom out past your home folder and the map grows to the volume root.

The rules that make it a truth instrument:

- Hidden folders always shown. ~/Library is where the bodies are buried.

- Unreadable space is drawn, not dropped. Other users' homes render as explicit "denied" tiles. A map that omits what it can't read cannot explain a mystery.

- The details dialog reconciles the two truths: Free, Reclaimable, Available-up-to - on my machine, 124.73 + 388.97 = 513.70, to the hundredth of a gigabyte. Both "free" numbers, one line.

- A full census in seconds. 2.83 million files scanned in 17.5 seconds — 161,000 files per second.

What the map found on my "clean" Mac

54 GB: a hostage snapshot. A Time Machine backup interrupted in August pinned a local snapshot — invisible everywhere, holding every block I changed for two weeks. One completed backup released it.

177 GB: secret BMPs. ~/Library/Containers/com.apple.wallpaper.agent/…/extension-com.apple.wallpaper.extension.image — 5,384 uncompressed bitmaps at 3456×2234, one per wallpaper rotation, converted from my 6 GB stash of JPEGs. macOS never cleaned them. Not purgeable either - they sat through months of disk pressure. The wallpaper system had already eaten my disk with aerial videos and my CPU with an animated "hello"; this made it a trilogy.

3.9 GB: archaeology. Twenty-four "Previously Relocated Items" folders - one per OS upgrade since 2022 - holding old Siri voice models and, yes, more wallpaper assets.

Total: ~235 GB, none of it findable by deleting caches, all of it visible as glowing rectangles once a census drew them.

A disk cleaner that deletes nothing

Terrazzo has no delete button. Right-click → Open in Finder, look at the thing with your own eyes, and decide. The tool's job ends at the truth.

That's a design position: every deletion in this story was mine, made calmly, because I could finally see what I was deciding about. The commercial cleaners invert that — they delete confidently on your behalf, using the same blind ledgers that couldn't explain my missing space in the first place.

Where it stands

Work in progress, built in public: github.com/andreirx/terrazzo

Working today: the full-speed census, the live-painting map, zoom navigation to the volume root, honest denied/unaccounted accounting, a watchlist, sqrt scaling, and a live map that retires rectangles the moment you delete the real thing.

Built the same way as my other projects: I ratify decisions, one AI builds, a second AI attacks every diff, and the fights reach me only when they matter. The reviewer blocked an architecture change it wasn't authorized to accept and refused to certify a diff that changed while it read it. Both times it was right.

If your Mac's free space doesn't add up - build & run terrazzo. You're welcome.