mac-cleanup-go

Preview-first TUI for cleaning macOS caches, logs, and temporary files.

English | 한국어

Overview

• Select items that take up space and delete them yourself.
• By default, items go to Trash; only the Trash category empties it permanently.
• Risky categories are unselected by default; even when selected, items are auto-excluded. (Include them in Preview to delete.)
• Manual categories show guides only.
• Scope: caches/logs/temp and selected app data (no system optimization or uninstaller).

Quick Start

1) Install

brew install mac-cleanup-go

Or download the archive from GitHub Releases.

2) Optional: Full Disk Access (needed for Trash/restricted locations) System Settings -> Privacy & Security -> Full Disk Access -> add Terminal

3) Run

mac-cleanup

Tip: Use Enter to preview, then y to proceed with deletion. Press ? to see key bindings.

• Update: brew upgrade mac-cleanup-go or mac-cleanup --update.
• Uninstall: brew uninstall mac-cleanup-go.
• Debug: mac-cleanup --debug saves log to ~/.config/mac-cleanup-go/debug.log.

Key bindings

List view:

• Up/Down or k/j: move
• Space: select category
• a: select all, d: deselect all
• Enter or p: preview selection
• ?: help, q: quit

Preview view:

• Up/Down or k/j: move
• h/l: previous/next category
• Space: toggle exclude
• Enter: drill into directory
• /: search, s: sort, o: open in Finder
• a: include all, d: exclude all
• y: delete (confirm), esc: back

Confirm view:

• y or Enter: confirm
• n or esc: cancel

CLI mode

Configure targets and clean from the command line.

mac-cleanup --select                   # Configure cleanup targets
mac-cleanup --clean --dry-run          # Preview cleanup report
mac-cleanup --clean                    # Execute cleanup

For command-line cleanup, see the examples below.

Example output

1) Select targets

$ mac-cleanup --select

Select cleanup targets                  ● safe  ○ moderate
─────────────────────────────────────────────────────────
        Name                                      Size
  [ ] ● Trash                                      0 B
  [✓] ○ App Caches                              3.2 GB
  [✓] ○ System Logs                           259.7 MB
▸ [✓] ● Go Build Cache                        845.0 MB
  [✓] ○ Docker                                  2.8 GB
  [✓] ● Homebrew Cache                          1.5 GB
  [ ] ● Chrome Cache                               0 B
─────────────────────────────────────────────────────────
Selected: 5
↑/↓ Move  space Select  s Save  ? Help  q Cancel

2) Preview / Clean

$ mac-cleanup --clean --dry-run

Dry Run Report
--------------
Mode: Dry Run

Summary                             Highlights
Freed (dry-run): 8.6 GB             1. App Caches - 3.2 GB (523 items)
                                    2. Docker - 2.8 GB (12 items)
                                    3. Homebrew Cache - 1.5 GB (34 items)

Details
STATUS  CATEGORY              ITEMS        SIZE
OK      App Caches              523      3.2 GB
OK      Docker                   12      2.8 GB
OK      Homebrew Cache           34      1.5 GB
OK      Go Build Cache           89    845.0 MB
OK      System Logs              67    259.7 MB

How it works & safety

• Scans known cache/log/temp paths across apps and tools in parallel.
• Lets you preview items and exclude what you want to keep.
• Labels targets by impact level (safe, moderate, risky, manual).
• SIP-protected paths are excluded from scan/cleanup.
• Built-in scans for Homebrew, Docker, and old downloads (brew/docker output or last-modified time filtering).

Impact levels

• safe: auto-regenerated caches/logs.
• moderate: may require re-download or re-login.
• risky: user data possible; items start excluded.
• manual: no automatic deletion; shows an app guide only.

Targets (as of v1.3.6)

• Total targets: 107.
• Groups: System 7, Browsers 10, Development 35, Applications 52, Storage 3.
• Cleanup methods: trash 101, permanent 1, builtin 3, manual 2.
• Builtins: homebrew, docker, old-downloads (built-in scanners using brew/docker output or last-modified time filtering).
• Manual: telegram, kakaotalk (no automatic deletion; surfaces large data like chat caches).
• Counts are release-based and may change over time.

Alternatives

• mac-cleanup-py - Python cleanup script for macOS
• Mole - Deep clean and optimize your Mac

License

MIT