Find the dead weight in your cargo hold.
A personalized, reversible disk-cleanup CLI for macOS. It finds your reclaimable bloat, pressure-tests every candidate against live disk state, and stages it in a 7-day airlock — so nothing is permanently deleted until you say so. Drivable by humans and agents.
The core idea
Some bytes come back on their own. Some don't. Treat them differently.
Every dev Mac hoards hundreds of GB. Blunt cleaners nuke it all and pray. diskspace knows which bytes regenerate for free and which carry consequences — and it routes them through different doors. Every rule declares its own recovery story.
Free to reclaim
Caches and build artifacts rebuild or re-download on demand. Reclaiming them costs you a few seconds later, nothing more.
- Xcode DerivedData · node_modules
- Homebrew / npm / cargo / pip caches
- browser + on-device AI model stores
- Docker volumes · build output
Handle with care
Downloads, project state, and anything irreversible get the slow lane — pressure-tested, airlocked, never silently deleted.
- old DMGs & installers in ~/Downloads
- local project state & databases
- files you actually opened recently
- anything your profile marks never-touch
The trust model
You can trust it without watching it.
Confidence is just a sort key. The pressure-test is the real safety boundary — if a candidate fails it, the action is blocked no matter how big the win. And the default path is always reversible.
scan
Parallel walk. Local bytes only — iCloud/Dropbox online-only files skipped.
detect
91 rules rank candidates by yield × confidence.
check
4-validator pressure-test. Fails loudly. The hard boundary.
airlock ↩
Reversible hold for 7 days. Restore or undo anytime.
purge
Permanent — and only ever a deliberate, separate step.
Four validators, every time
A candidate only moves if it survives all four:
- re-stat — size unchanged since detect
- liveness — no open handles, no writes <24h
- policy — not in your never-touch list
- recency — no recent git activity nearby
Reversible by default
Below the high-confidence floor, everything goes to ~/.diskspace/airlock/ first, with a manifest and a 7-day window. Restore is always one command away.
Honest accounting
Every action is logged with the real df delta — never a fictional number. A same-volume move says so; it doesn't pretend to free space until you purge.
"actually_freed":114765824, "reversible":true,
"undo_cmd":"diskspace restore chrome-cache-b97…"}
Built for agents too
Safe to auto-invoke. Same binary humans use.
When a build dies with No space left on device, an agent can recover the disk and retry — unattended — precisely because the airlock and pressure-test make it safe where a blunt rm -rf would not be. Every command speaks --json and honors a stable exit-code contract.
| 0 | success — space freed, proceed |
| 1 | no candidates — nothing safe to free |
| 2 | pressure-test failed — stop, don't force |
| 3 | policy blocked — path is never-touch |
| 127 | unknown error — inspect, don't retry blindly |
Get it
One binary. Two minutes.
Homebrew
$ brew install tymrtn/diskspace/diskspace
The recommended path. Tap + formula maintained for every release.
Cargo
$ cargo install diskspace-cli
The package is diskspace-cli; the installed binary is still diskspace.