An open-source macOS storage cleanup utility for developers.
Scan, review, and reclaim disk space — safely, transparently, and from the terminal.
- Interactive TUI to browse and select what to clean
- Dry-run by default — nothing is deleted without your explicit confirmation
- Modular cleaners for different categories of junk
- Progress reporting and summary of reclaimed space
- Export scan results as JSON or CSV
- Generate shell cleanup scripts from scan results
- Target specific categories in any command
macOS can accumulate large amounts of storage in places that are hard to inspect, especially caches, developer artifacts, logs, and vague categories like “System Data”.
TidyMyMac was built to make cleanup transparent and safe:
- inspect first
- review before deleting
- dry-run by default
- stay fully terminal-native
| Category | What it targets |
|---|---|
| Temporary Files | /tmp, /var/tmp, user temp directories |
| Application Caches | ~/Library/Caches |
| System Logs | ~/Library/Logs, /Library/Logs, /var/log |
| Homebrew Cache | Packages cached by brew |
| Docker Artifacts | Stopped containers, untagged images, orphaned volumes |
| iOS Backups | iPhone/iPad backups in ~/Library/Application Support/MobileSync/Backup |
| macOS Updates | Old macOS update residues and installers |
| Xcode | DerivedData, archives, simulators |
| Development Artifacts | Go build cache and downloaded module cache |
| Time Machine Snapshots | Local Time Machine snapshots stored on disk |
| Trash | Files in the Trash waiting to be permanently removed |
brew install viniciussouzao/tap/tidymymacgo install github.com/viniciussouzao/tidymymac/cmd/tidymymac@latestMake sure $(go env GOPATH)/bin is in your PATH.
git clone https://github.com/viniciussouzao/tidymymac
cd tidymymac
make build
./bin/tidymymacRequires Go 1.21+
# Launch interactive TUI (dry-run, nothing is deleted)
tidymymac
# Actually delete the selected files
tidymymac --execute
# Interactive table (default)
tidymymac scan
# Scan specific categories only
tidymymac scan docker caches xcode
# Output as JSON or CSV
tidymymac scan --output json
tidymymac scan --output csv
# Include individual file paths in output
tidymymac scan --output json --detailed
# Save output to a timestamped file
tidymymac scan --output csv --save
# Generate a shell cleanup script from scan results
tidymymac scan --generate-script
# Suppress progress output (useful in scripts)
tidymymac scan --output json --quiet# Preview what would be deleted (dry-run, default)
tidymymac clean
# Actually delete files
tidymymac clean --execute
# Clean specific categories
tidymymac clean docker caches --execute
# Use a previously saved detailed scan instead of re-scanning
tidymymac clean --from-file scan.json --execute
# Output cleanup result as JSON
tidymymac clean --output jsontidymymac version # Print version, commit, build date, platform, and Go version
tidymymac explain # Explain what each category contains
tidymymac history # Show past cleanup runsmake build # Compile binary to bin/tidymymac
make test # Run tests with race detection
make run # Build and run
make clean # Remove build artifactsTidyMyMac is designed with safety as the primary concern:
- ✅ Dry-run by default: scanning and reviewing never touches your files
- ✅ Explicit confirmation required: deletion only happens with
--execute - ✅ No silent operations: every file is shown before removal
- ✅ Errors are non-fatal: a failure on one file won't stop the rest
Running into empty scan results, permission issues, or other surprises? Check docs/TROUBLESHOOTING.md — the most common one is a terminal missing Full Disk Access on macOS, which makes Trash and a few other categories report 0 B even when they aren't empty.
This project is licensed under the MIT License - see the LICENSE file for details.