<[BACK TO ARCHIVE]
#pythonclimacosdevtoolsopen-source

Building mac-sweep: A Fast macOS Cleanup CLI in Python

How I built a beautiful, safety-first CLI tool that hunts down junk files, caches, and cruft on macOS — with dry-run mode, rollback manifests, and Rich-powered output.

[]SYS.DATE :: March 20, 2026

Every developer's Mac eventually becomes a digital hoarder. Gigabytes of node_modules graveyards, stale Xcode derived data, abandoned pip caches, three generations of iOS simulator runtimes — it all adds up.

I wanted a single command that would honestly audit the mess, let me review it, and clean it safely. After not finding quite what I was looking for, I built mac-sweep — a fast, beautiful, and safety-first CLI tool for macOS.

The Problem

Most cleanup tools either:

  • Delete things without telling you what they're deleting (dangerous)
  • Show you a wall of text with no structure (useless)
  • Lock real features behind a subscription (annoying)

I wanted something with the honesty of a dry-run flag, the clarity of a well-designed table, and the safety of a rollback manifest.

Design Principles

Three rules guided every decision:

  1. Preview before you commit. Every destructive operation supports --dry-run.
  2. Risk transparency. Each scan target is labelled Safe: ✓ (auto-regenerated by the OS) or Safe: ! (may contain data you care about).
  3. Reversibility. When cleaning in --delete-mode trash, mac-sweep writes a rollback manifest to ~/.mac_sweep/manifests/ so you can restore items later.

What It Scans

mac-sweep knows about 20+ junk locations across 9 categories:

| Category | Examples | |-----------|---------| | cache | User & system caches (~/Library/Caches) | | browser | Chrome, Safari caches | | package | npm, pip, Homebrew, Yarn, Gradle, Maven | | dev | Xcode DerivedData, simulators, Docker layers | | logs | App logs, crash reports, system logs | | backup | iOS backups, Time Machine local snapshots | | apps | Leftover app support files after uninstall | | system | Trash, language packs | | user | Downloads, other large user directories |

The Commands

scan — survey the damage

mac-sweep scan
mac-sweep scan --category cache package dev
mac-sweep scan --top 10 --age-days 30
mac-sweep scan --json   # pipe-friendly output

Outputs a sorted table: location, size, safety rating, age. Sorted by size so the biggest offenders are always at the top.

clean — interactive deletion

mac-sweep clean                      # prompts for each location
mac-sweep clean --safe-only --yes    # fully automatic safe clean
mac-sweep clean --dry-run            # preview only
mac-sweep clean --risk-level safe --delete-mode trash

Each run writes a rollback manifest so nothing is truly gone unless you empty the trash.

large — hunt down space hogs

mac-sweep large                 # files > 100 MB in home
mac-sweep large --min-mb 500   # raise the threshold
mac-sweep large --path ~/Movies

Useful when a rogue video export or VM snapshot is eating your disk.

doctor — quick health snapshot

mac-sweep doctor

Shows disk usage %, macOS version, Homebrew outdated package count, Trash size, and total cache size — in under a second.

restore — undo a cleanup

mac-sweep restore --list
mac-sweep restore --manifest ~/.mac_sweep/manifests/cleanup-20260320-143200.json

Implementation Notes

The project is organised as a proper Python package:

macsweep/
├── __main__.py       # python -m macsweep entrypoint
├── cli.py            # argparse routing
├── config.py         # scan targets, risk config
├── utils.py          # size helpers, Rich rendering, JSON
└── commands/
    ├── scan.py
    ├── clean.py
    ├── large.py
    ├── doctor.py
    └── restore.py

A few things worth calling out:

Rich for output. The Rich library makes the tables and progress indicators look great. It degrades gracefully if Rich isn't installed — falling back to plain text.

JSON mode everywhere. Every command supports --json for scripting. Useful for cron jobs that log cleanup results or pipe into jq.

Rollback manifests. When you use --delete-mode trash, mac-sweep records a JSON manifest with every moved path so restore can put things back without guesswork.

Install

git clone https://github.com/Rahul-Sahani04/mac-sweep
cd mac-sweep
bash install.sh   # sets up .venv and installs to /usr/local/bin

Then just run:

mac-sweep scan

What's Next

A few things I'm thinking about adding:

  • Scheduled clean profiles — define a safe set of targets and run them weekly via launchd
  • Homebrew integration — surface outdated packages inside doctor
  • Interactive TUI — a Textual interface for browsing scan results

If any of that sounds useful to you, PRs are welcome.

// END_OF_TRANSMISSION