🧹 CleanDrive

Every "disk cleaner" on the Mac falls into one of two camps: dumb (blindly nukes ~/Library/Caches and prays) or dangerous (one-click "free up 200 GB" that also eats the project you shipped last week). CleanDrive is neither.

It starts from a hard rule: nothing gets deleted that can't be regenerated or hasn't been verified onto another disk first. Your caches? Delete freely — they rebuild. Your actual projects? They can only leave this machine by being copied to an external drive, checksum-verified, and only then removed locally. And the things you never want touched — your Claude agent history, your coding sessions — are hard-locked and refused even if something tries to force the action.

git clone https://github.com/kaiser-data/cleandrive.git
cd cleandrive
cp config.example.json config.json     # point projectRoots at your code folders

node bin/cleandrive.js scan            # ~1–3 min; writes data/latest.json
node bin/cleandrive.js serve           # dashboard → http://localhost:4499

Open the dashboard, approve what you want gone, type FREE, watch it work. That's it.

No dependencies to install. CleanDrive is pure Node stdlib + your system's du, find, rsync, and ssh. node_modules/ never appears in this repo.

                         ┌─────────────────────────────────────────────┐
   scan produces  ─────▶ │  every actionable path is an allowlist entry │
   the ONLY               └─────────────────────────────────────────────┘
   actionable set                        │
                                          ▼
   ┌──────────────┬───────────────────────────────────────────────────────┐
   │ category      │ what's allowed                                        │
   ├──────────────┼───────────────────────────────────────────────────────┤
   │ pkgcache      │ official clean cmd (uv/npm/brew/pnpm/bun) — or rm      │
   │ cache         │ rm  (the app rebuilds it)                             │
   │ node_modules  │ rm  (reinstall per project)                          │
   │ projects      │ archive / archive+rm / keep  — NEVER a bare rm        │
   │ appdata       │ rm only after explicit "mark reviewed" + approve      │
   │ apps          │ review only — surfaced with size + last-used         │
   │ models        │ rm after review — or remove via the owning tool      │
   └──────────────┴───────────────────────────────────────────────────────┘

Enforced at every layer, not just the UI:

• Allowlist by construction — only paths that came out of the scan are actionable; anything else is refused.
• rm is category-gated — permitted only for pkgcache, cache, node_modules. A project can leave solely via archive+rm, and only after checksum verification passes.
• Protected paths are hard-locked — listed in config.protected, refused at the executor even if a forged action reaches it. Ships protecting your Claude/agent history.
• Protected roots — ~, ~/Documents, ~/Desktop, ~/Downloads, ~/Pictures, ~/Library are refused as direct targets regardless of plan content.
• Localhost only — the dashboard binds to 127.0.0.1, and execution requires typing the word FREE.
• Full audit trail — every start/finish lands in data/actions.log as JSONL.

CleanDrive was built to be driven by an agent. The CLI speaks --json, and the state lives in flat files, so a Claude Code session can run the whole loop — and never act without your say-so:

node bin/cleandrive.js state --json          # items: {id, path, kb, category, suggest, note}
node bin/cleandrive.js approve <id…> --action=archive+rm
node bin/cleandrive.js execute --dry-run     # show exactly what would happen
node bin/cleandrive.js execute               # do it — logged to data/actions.log

A typical session: Claude reads your scan, groups it by category, proposes "here's 33 GB of package caches and 14 GB of node_modules, all regenerable — clean them?", and only after you confirm the specific items does it approve and execute. The plan is always yours.

1. Attach an external drive to any machine on your Tailscale network.
2. In the dashboard's Remote archive target card (or config.json), set the device's Tailscale name, the SSH user, and a destination path.
3. Hit Test connection — it verifies SSH reachability and shows the remote's free space.
4. Set a project's action to archive (copy only) or archive+rm (copy, verify, then reclaim locally).

Files are rsync'd with -aHR so the path relative to your home folder is preserved on the remote — your archive mirrors your Mac's layout, making restores obvious.

bin/cleandrive.js     CLI + agent connector (every command is scriptable)
lib/scan.js           the scanner — categorization, sizing, staleness, app usage
lib/actions.js        the executor — validation, rm/clean/archive, verification, audit log
lib/server.js         zero-dep HTTP API + static host for the dashboard
lib/util.js           shell helpers, hashing, concurrency pool
ui/index.html         the single-file dashboard (validated colorblind-safe palette)
config.json           your roots, thresholds, protected paths, remote target
data/                 latest.json (scan) · plan.json (approvals) · actions.log (audit)

CleanDrive — the scanner, the safety model, the dashboard, the Playwright capture pipeline that produced the demo above — was designed and implemented in a Claude Code session. Which is exactly why protecting agent history is a first-class feature: the tool knows what it must never delete.