🧹 Cleanbuddy

Your Mac fills up with .next build caches, bloated node_modules, a sprawling Docker.raw, a fat pnpm store, and system caches. Cleanbuddy clears all of it — safely. It only ever deletes data that regenerates, and it never touches your source code, git history, .env files, the node_modules of projects you're actively working on, or your Docker volumes.

The worst thing that can ever happen: a slightly slower next build, or one pnpm install for a project you hadn't touched in a month.

• 🎛️ Beautiful TUI powered by gum — color-coded by risk, live progress, a real disk gauge.
• 🤖 Automatic spring clean — a launchd watcher checks your free space daily and quietly clears the safe stuff when you're running low, then pings you a macOS notification.
• 🛡️ Safety-first by design — active projects are detected and protected; every deletion goes through a guarded allowlist (safe_rm) with full symlink resolution; Docker is manual-only and never runs with --volumes.
• ⚡ Fast — parallel scanning; sizes measured with du (real blocks), never ls (a sparse Docker.raw lies: 460 GB apparent, ~60 GB real).
• 🧪 Solid — 130 tests via a dependency-free pure-bash harness, shellcheck-clean.

git clone https://github.com/Codevena/cleanbuddy.git ~/tools/cleanbuddy
cd ~/tools/cleanbuddy
brew install gum bash       # gum = the TUI; bash ≥ 4 (macOS ships 3.2)
./install.sh                # symlinks `cleanbuddy` + installs the daily watcher

Requirements: macOS, bash ≥ 4 (brew install bash), gum. (jq is used by the optional Docker cleaner.)

cleanbuddy                  # interactive menu
cleanbuddy --scan           # just show what's eating space (read-only)
cleanbuddy --auto           # clean the safe categories, non-interactively
cleanbuddy uninstall        # remove the watcher + symlinks (keeps your config)

Menu: Spring Clean · Select · Scan only · Docker · History · Settings · Quit. Every destructive action shows a preview and asks before deleting.

Active projects are protected. A project counts as active if its newest git commit or its newest working-tree file is more recent than INACTIVE_DAYS — so anything you've touched (even uncommitted) keeps its node_modules.

• Deletion only through safe_rm — an allowlist of roots, full symlink resolution (pwd -P), and hard refusals for empty paths, .., symlinks, and the roots themselves. Nothing outside the allowlist can ever be removed.
• du, never ls for sizing, so sparse files like Docker.raw report their real on-disk usage.
• The watcher only ever touches the safe categories. Docker is never cleaned automatically; it requires the menu, an extra red confirm, and never passes --volumes.

~/.config/cleanbuddy/config (or edit it interactively via the Settings menu):

THRESHOLD_GB=25            # watcher auto-cleans when free space drops below this
INACTIVE_DAYS=30           # a project untouched this long counts as inactive
BASE_DIR="$HOME/Developer" # where your projects live
WATCH_HOUR=13              # daily watcher time, 0–23 (re-run ./install.sh after changing)
ENABLE_DEVELOPER=true      # .next + node_modules
ENABLE_PNPM=true
ENABLE_CACHES=true
ENABLE_DOCKER=true

./install.sh installs a launchd LaunchAgent (com.codevena.cleanbuddy.watch) that runs daily at WATCH_HOUR. If free space is below THRESHOLD_GB it cleans the safe categories and sends a notification — otherwise it does nothing. Logs land in ~/.config/cleanbuddy/.

bash tests/run.sh                       # 130 checks, pure-bash, zero deps
shellcheck -x cleanbuddy*.sh lib/*.sh lib/cleaners/*.sh
vhs demo/cleanbuddy.tape                # re-record the demo GIF (drives a /tmp fixture)

Architecture: small single-responsibility modules under lib/, a uniform cleaner contract (<name>_scan → candidate lines, <name>_clean → frees + reports), one orchestrator, one watcher. Design notes live in docs/superpowers/.

Cleanbuddy deletes files. It is built to be safe and is well-tested, but use it at your own risk — review the preview (or cleanbuddy --scan) before you confirm.

MIT © 2026 Markus Wiesecke / Codevena