Buildingmac-sweep:AFastmacOSCleanupCLIinPython

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:

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.