↓Skip to main content

mac-cleaner: A Safe macOS Cleanup CLI

·691 words·4 mins
Table of Contents

GitHub Repo: cleanmymac-shell

Project Overview #

mac-cleaner is a lightweight macOS cleanup tool written in shell.

The goal is simple: help users reclaim disk space without turning cleanup into a dangerous one-click operation. Instead of deleting files immediately, mac-cleaner follows a conservative, review-first workflow. By default, it runs in dry-run mode, scans common cleanup targets, and shows what could be cleaned before anything is moved.

It can inspect old caches, logs, crash reports, temporary files, developer artifacts, package manager caches, large files, applications, startup items, and optional cleanup areas such as Downloads, Trash, Docker, and Xcode archives.

The project is designed around three ideas:

  1. Safe by default — dry-run first, no accidental deletion.
  2. Review before action — users can inspect cleanup candidates before executing.
  3. Recoverable cleanup — approved items are moved to a timestamped folder under ~/.Trash/mac-cleaner-* instead of being permanently removed.

This project is mainly built for developers and power users who prefer transparent command-line tools over black-box cleanup apps. It is not trying to replace commercial macOS maintenance software. It is a small, auditable, shell-based utility for people who want to understand exactly what is being cleaned.

Development Workflow: AI-Assisted, Human-Led #

fig-01-ai-assisted-human-led-development-workflow

This project was also an experiment in AI-assisted software development.

In this workflow, I acted as the Product Manager and Project Owner, responsible for the product direction, safety principles, feature scope, and final engineering decisions.

I treated different AI tools as members of a small virtual software team:

  • OpenAI Codex acted like the CTO, helping with architecture thinking, implementation strategy, code structure, and technical trade-offs.
  • ChatGPT acted like the UI/UX designer and technical editor, helping refine user experience, command-line interaction, documentation, and project messaging.
  • Google Antigravity acted like the developer, helping implement features, iterate on shell scripts, and debug behavior.
  • GitHub Copilot acted like the DevOps assistant, helping with repository maintenance, automation, release workflow, and day-to-day coding support.

I also treated AI usage limits as part of the engineering workflow. When one tool ran out of tokens, credits, or usage quota, another AI tool could step in as the next available developer.

This made the process less dependent on a single model or platform, and more like working with a flexible, rotating AI development team.

The final design still followed a human-led engineering workflow. AI tools accelerated implementation and review, but the project direction, safety model, cleanup rules, and final decisions remained manually reviewed and intentionally conservative.

Try it safely #

Start with --dry-run before executing anything.

fig-02-mac-cleaner-coverage

Example usage:

curl -L https://github.com/cuicaihao/cleanmymac-shell/releases/latest/download/mac-cleaner.tar.gz -o mac-cleaner.tar.gz
tar -xzf mac-cleaner.tar.gz
chmod +x mac-cleaner
mkdir -p "$HOME/.local/bin"
mv mac-cleaner "$HOME/.local/bin/mac-cleaner"
mac-cleaner --help
mac-cleaner --dry-run

The project will continue to evolve as I refine the cleanup rules, improve safety checks, and add more developer-focused maintenance workflows.

A Real Dry Run #

I tested the latest release locally with the default dry-run mode:

curl -L https://github.com/cuicaihao/cleanmymac-shell/releases/latest/download/mac-cleaner.tar.gz -o mac-cleaner.tar.gz
tar -xzf mac-cleaner.tar.gz
chmod +x mac-cleaner
mkdir -p "$HOME/.local/bin"
mv mac-cleaner "$HOME/.local/bin/mac-cleaner"

mac-cleaner --help
mac-cleaner --dry-run

The dry run completed safely without moving or deleting any files:

✨ mac-cleaner v1.2.0
────────────────────────────────────────────────────────
Command:       scan
Mode:          Dry Run (Safe mode, preview only)
Age Threshold: > 14 day(s)
────────────────────────────────────────────────────────

== Cleanup plan ==
❯ User cache contents older than threshold [low risk]
  Note: Usually safe to regenerate. Apps may rebuild these files later.
  └── Total: 15.6 MiB  (6 items)

❯ Developer caches [medium risk]
  Note: Usually safe to regenerate, but the next build, package install, or simulator launch may be slower.
  └── Total: 173.4 MiB  (3 items)

Dry-run cleanup script written to: clean.sh
All rm -rf lines are commented. Review, edit, and run it yourself only if you are confident.

== Skipped optional groups ==
  Old Xcode archives: skipped. Use --include-xcode-archives to include Organizer archives older than the threshold.
  Downloads older than threshold: skipped. Use --include-downloads to include ~/Downloads.
  Trash: skipped. Use --empty-trash to include ~/.Trash.
  Docker cleanup: skipped. Use --include-docker to prune Docker caches and stopped resources.

📊 Final Summary
────────────────────────────────────────────────────────
Can be reclaimed:           9 items      189.0 MiB
Actually moved:             0 items            0 B
Scan time:                       less than 1s
────────────────────────────────────────────────────────

This output reflects the main design principle of the project: scan first, review clearly, and avoid destructive cleanup by default.