macOS Scheduled Cleanup #

Automated weekly system maintenance for macOS. Cleans browser caches, package manager caches, Xcode cruft, language-specific caches, Docker artifacts, and temp files. Reports space freed via macOS Notification Center.

Runs via launchd on a schedule. No manual intervention needed.

What it cleans #

Module	What	Guard
Edge	IndexedDB, Service Worker caches, disk cache	Skips if Edge not installed
Homebrew	`brew cleanup --prune=all`	Skips if brew not found
Xcode	DerivedData (7+ days stale), simulator caches, old iOS device support	Skips if Xcode not installed
npm	`npm cache clean --force`	Skips if npm not found
pip	`pip3 cache purge`	Skips if pip3 not found
Cargo	`~/.cargo/registry/cache/` and git checkouts	Skips if `~/.cargo` missing
Docker	`docker system prune -f` (containers, networks, dangling images)	Skips if Docker not running
Temp files	`$TMPDIR` files older than 1 day (user-owned only)	Always safe

What it does NOT touch #

System logs (/var/log, ~/Library/Logs)
Trash
Anything requiring sudo
Xcode DerivedData from the last 7 days (won't break active builds)

Quick install #

git clone git@tangled.org:psingletary.com/macOS-sched-cleanup.git
cd macOS-sched-cleanup
./install.sh

Default schedule: Sunday at 11:00 AM.

Custom schedule #

./install.sh --day 1 --hour 15          # Monday at 3:00 PM
./install.sh --day 6 --hour 2 --minute 30  # Saturday at 2:30 AM

Days: 0 = Sunday, 1 = Monday, ..., 6 = Saturday.

Uninstall #

./install.sh --uninstall

Removes the launchd plist and ~/.scripts/clean.sh. Logs are left in place.

How it works #

launchd fires on schedule (or coalesces to next wake if machine was asleep)
clean.sh runs, measuring disk space before and after each module
Results are logged to ~/.logs/cleanup.log (rotated every 12 weeks)
A macOS notification summarizes what was freed

If the machine is asleep at the scheduled time, launchd runs the job when the machine next wakes — it does not force a wake.

Test it immediately #

~/.scripts/clean.sh

Run it manually to see the output and verify the notification.

Requirements #

macOS (tested on Sequoia/Sonoma)
terminal-notifier for notifications: brew install terminal-notifier
bc (included with macOS, used for byte formatting)

Everything else is optional — modules silently skip if their target software isn't installed.

Logs #

~/.logs/cleanup.log — stdout from each run
~/.logs/cleanup-error.log — stderr from each run
Rotated logs: ~/.logs/cleanup-YYYY-MM-DD.log (purged after 12 weeks)

License #

MIT

Clone this repository