mac-cleaner

README

mac-cleaner

A fast, safe CLI tool for reclaiming disk space on macOS.

English | Polski | Deutsch | Українська | Русский | Français

Features

System Caches

• User App Caches — ~/Library/Caches/ (safe)
• User Logs — ~/Library/Logs/ (safe)
• QuickLook Thumbnails — per-user QuickLook cache (safe)

Browser Data

• Safari Cache — ~/Library/Caches/com.apple.Safari/ (moderate)
• Chrome Cache — ~/Library/Caches/Google/Chrome/ across all profiles (moderate)
• Firefox Cache — ~/Library/Caches/Firefox/ (moderate)

Developer Caches

• Xcode DerivedData — ~/Library/Developer/Xcode/DerivedData/ (risky)
• npm Cache — ~/.npm/ (moderate)
• Yarn Cache — ~/Library/Caches/yarn/ (moderate)
• Homebrew Cache — ~/Library/Caches/Homebrew/ (moderate)
• Docker Reclaimable — containers, images, build cache, volumes (risky)
• iOS Simulator Caches — ~/Library/Developer/CoreSimulator/Caches/ (safe)
• iOS Simulator Logs — ~/Library/Logs/CoreSimulator/ (safe)
• Xcode Device Support — ~/Library/Developer/Xcode/iOS DeviceSupport/ (moderate)
• Xcode Archives — ~/Library/Developer/Xcode/Archives/ (risky)
• pnpm Store — ~/Library/pnpm/store/ (moderate)
• CocoaPods Cache — ~/Library/Caches/CocoaPods/ (moderate)
• Gradle Cache — ~/.gradle/caches/ (moderate)
• pip Cache — ~/Library/Caches/pip/ (safe)

Project Caches

• node_modules — node_modules/ directories in JavaScript/TypeScript projects (safe)
• .build (Swift) — .build/ directories in Swift Package Manager projects (safe)
• target (Rust) — target/ directories in Cargo/Rust projects (safe)
• venv (Python) — venv/ and .venv/ directories in Python projects (moderate)
• build (Java/Kotlin) — build/ directories in Gradle/Maven projects (safe)

Project caches are detected by walking your home directory and validating each candidate against its manifest file (e.g., package.json for node_modules, Cargo.toml for target). This prevents false positives on generic directory names. Projects inactive for 6+ months are flagged with a staleness indicator.

Home Directory Files

• Large Files (>100 MB) — files larger than 100 MB found in your home directory (risky)
• Old Files (>180 days) — files older than 180 days and larger than 10 MB found in your home directory (risky)

Home directory scanning excludes ~/Library, ~/Applications, ~/.Trash, ~/Downloads, and dotfile directories (e.g., ~/.config). Results are marked as "risky" because these are personal files, not regenerable caches.

Note: iCloud Drive placeholder files may report their original size even when evicted from local storage.

Git Repository Cleanup

• Git Repositories — .git/ directories found via home directory walk (moderate)

Git repository cleanup discovers .git directories under your home folder, reports their size and estimated reclaimable space via git count-objects, and offers git gc --aggressive cleanup. For repositories with Git LFS (detected via .git/lfs), git lfs prune is run automatically when git-lfs is installed. Repositories with active operations (presence of index.lock) are safely skipped.

Note: Cleanup runs git gc --aggressive and git lfs prune — it does not delete any repository files. This is safe for all repositories.

App Leftovers

• Orphaned Preferences — .plist files in ~/Library/Preferences/ for uninstalled apps (risky)
• iOS Device Backups — ~/Library/Application Support/MobileSync/Backup/ (risky)
• Old Downloads — files in ~/Downloads/ older than 90 days (moderate)

Creative App Caches

• Adobe Caches — ~/Library/Caches/Adobe/ (safe)
• Adobe Media Cache — ~/Library/Application Support/Adobe/Common/Media Cache Files/ + Media Cache/ (moderate)
• Sketch Cache — ~/Library/Caches/com.bohemiancoding.sketch3/ (safe)
• Figma Cache — ~/Library/Application Support/Figma/ (safe)

Messaging App Caches

• Slack Cache — ~/Library/Application Support/Slack/Cache/ + Service Worker/CacheStorage/ (safe)
• Discord Cache — ~/Library/Application Support/discord/Cache/ + Code Cache/ (safe)
• Microsoft Teams Cache — ~/Library/Application Support/Microsoft/Teams/Cache/ + ~/Library/Caches/com.microsoft.teams2/ (safe)
• Zoom Cache — ~/Library/Application Support/zoom.us/data/ (safe)

Photos & Media Caches

• Photos App Caches — ~/Library/Containers/com.apple.Photos/ caches (safe)
• Photos Analysis Caches — ~/Library/Containers/com.apple.photoanalysisd/ ML model data (safe)
• iCloud Photos Sync Cache — ~/Library/Caches/com.apple.cloudd/ (moderate)
• Messages Shared Photos — ~/Library/Messages/Attachments/ synced media (risky)

System Data

• CoreSpotlight Metadata — ~/Library/Caches/com.apple.Spotlight/ (safe)
• Mail Database — ~/Library/Mail/ envelope index and data (risky)
• Mail Attachment Cache — ~/Library/Mail Downloads/ (moderate)
• Messages Attachments — ~/Library/Messages/ media and attachments (risky)
• iOS Software Updates — ~/Library/iTunes/iPhone Software Updates/ (safe)
• Time Machine Local Snapshots — local TM snapshot metadata (risky)
• Parallels VMs — ~/Parallels/ virtual machine disk images (risky)
• UTM VMs — ~/Library/Containers/com.utmapp.UTM/ virtual machines (risky)
• VMware Fusion VMs — ~/Virtual Machines.localized/ disk images (risky)

Unused Applications

• Unused Apps — applications in /Applications and ~/Applications not opened in 180+ days, with total disk footprint including ~/Library/ data (risky)

For details, see Unused Applications Detection.

Safety

mac-cleaner is designed to protect your system:

• SIP-protected paths are blocked — /System, /usr, /bin, /sbin are never touched (/usr/local is allowed)
• Swap/VM protection — /private/var/vm is always blocked to prevent kernel panics
• Symlink resolution — all paths are resolved before deletion to prevent escaping intended directories
• Three-tier risk levels — every category is classified as safe, moderate, or risky so you know what you're getting into
• Re-validation before deletion — safety checks run again at deletion time, not just during scanning
• Dry-run mode — preview everything before committing with --dry-run
• Interactive confirmation — explicit user approval required before anything is deleted (unless --force is used)

For a detailed security analysis, see Security Architecture.

Installation

Homebrew

brew install sp3esu/tap/mac-cleaner

Build from source

Prerequisites: Go 1.25+, macOS

git clone https://github.com/sp3esu/mac-cleaner.git
cd mac-cleaner
go build -o mac-cleaner .
./mac-cleaner --help

Shell Completion

Generate shell completion scripts for tab-completing flags and subcommands.

Bash:

# Load in current session:
source <(mac-cleaner completion bash)

# Install permanently:
mac-cleaner completion bash > /usr/local/etc/bash_completion.d/mac-cleaner

Zsh:

mac-cleaner completion zsh > "${fpath[1]}/_mac-cleaner"
# Then restart your shell or run: compinit

Fish:

mac-cleaner completion fish > ~/.config/fish/completions/mac-cleaner.fish

PowerShell:

mac-cleaner completion powershell | Out-String | Invoke-Expression

Usage

Interactive mode (default — walks you through each category):

./mac-cleaner

Scan everything, preview only:

./mac-cleaner --all --dry-run

Clean system caches without confirmation:

./mac-cleaner --system-caches --force

Scan everything, JSON output:

./mac-cleaner --all --json

Scan all but skip Docker and iOS backups:

./mac-cleaner --all --skip-docker --skip-ios-backups

Scan project build caches (node_modules, .build, target, venv, build):

./mac-cleaner --project-caches --dry-run

Scan for large and old files in home directory:

./mac-cleaner --home-files --dry-run

Scan git repositories for reclaimable cache space:

./mac-cleaner --git-repos --dry-run

Scan only node_modules directories:

./mac-cleaner scan --node-modules --dry-run

Targeted scan — specific items only (via scan subcommand):

./mac-cleaner scan --npm --safari --dry-run

Targeted scan — full group plus individual items:

./mac-cleaner scan --dev-caches --safari

Targeted scan — group minus specific items:

./mac-cleaner scan --dev-caches --skip-docker

Structured help for AI agents:

./mac-cleaner --help-json

CLI Flags

Scan Categories

Flag	Description
--all	Scan all categories
--system-caches	Scan user app caches, logs, and QuickLook thumbnails
--browser-data	Scan Safari, Chrome, and Firefox caches
--dev-caches	Scan Xcode, npm/yarn, Homebrew, and Docker caches
--project-caches	Scan project build caches (node_modules, .build, target, venv, build)
--home-files	Scan for large and old files in home directory
--git-repos	Scan for git repository caches
--app-leftovers	Scan orphaned preferences, iOS backups, and old Downloads
--creative-caches	Scan Adobe, Sketch, and Figma caches
--messaging-caches	Scan Slack, Discord, Teams, and Zoom caches
--unused-apps	Scan applications not opened in 180+ days
--photos	Scan Photos app caches and media analysis data
--system-data	Scan Spotlight, Mail, Messages, iOS updates, Time Machine, and VMs

Output & Behavior

Flag	Description
--dry-run	Preview what would be removed without deleting
--json	Output results as JSON
--verbose	Show detailed file listing
--force	Bypass confirmation prompt
--help-json	Output structured help as JSON for AI agents

Category Skip Flags

Flag	Description
--skip-system-caches	Skip system cache scanning
--skip-browser-data	Skip browser data scanning
--skip-dev-caches	Skip developer cache scanning
--skip-project-caches	Skip project cache scanning
--skip-home-files	Skip home directory file scanning
--skip-git-repos	Skip git repository scanning
--skip-app-leftovers	Skip app leftover scanning
--skip-creative-caches	Skip creative app cache scanning
--skip-messaging-caches	Skip messaging app cache scanning
--skip-unused-apps	Skip unused applications scanning
--skip-photos	Skip Photos cache scanning
--skip-system-data	Skip system data scanning

Item Skip Flags

Flag	Description
--skip-derived-data	Skip Xcode DerivedData
--skip-npm	Skip npm cache
--skip-yarn	Skip Yarn cache
--skip-homebrew	Skip Homebrew cache
--skip-docker	Skip Docker reclaimable space
--skip-safari	Skip Safari cache
--skip-chrome	Skip Chrome cache
--skip-firefox	Skip Firefox cache
--skip-quicklook	Skip QuickLook thumbnails
--skip-orphaned-prefs	Skip orphaned preferences
--skip-ios-backups	Skip iOS device backups
--skip-old-downloads	Skip old Downloads files
--skip-simulator-caches	Skip iOS Simulator caches
--skip-simulator-logs	Skip iOS Simulator logs
--skip-xcode-device-support	Skip Xcode Device Support files
--skip-xcode-archives	Skip Xcode Archives
--skip-pnpm	Skip pnpm store
--skip-cocoapods	Skip CocoaPods cache
--skip-gradle	Skip Gradle cache
--skip-pip	Skip pip cache
--skip-node-modules	Skip node_modules directories
--skip-swift-build	Skip .build (Swift) directories
--skip-rust-target	Skip target (Rust) directories
--skip-python-venv	Skip venv (Python) directories
--skip-java-build	Skip build (Java/Kotlin) directories
--skip-large-files	Skip large files in home directory
--skip-old-files	Skip old files in home directory
--skip-adobe	Skip Adobe caches
--skip-adobe-media	Skip Adobe media caches
--skip-sketch	Skip Sketch cache
--skip-figma	Skip Figma cache
--skip-slack	Skip Slack cache
--skip-discord	Skip Discord cache
--skip-teams	Skip Microsoft Teams cache
--skip-zoom	Skip Zoom cache
--skip-photos-caches	Skip Photos app caches
--skip-photos-analysis	Skip Photos analysis caches
--skip-photos-icloud-cache	Skip iCloud Photos sync cache
--skip-photos-syndication	Skip Messages shared photos
--skip-spotlight	Skip CoreSpotlight metadata
--skip-mail	Skip Mail database
--skip-mail-downloads	Skip Mail attachment cache
--skip-messages	Skip Messages attachments
--skip-ios-updates	Skip iOS software updates
--skip-timemachine	Skip Time Machine local snapshots
--skip-vm-parallels	Skip Parallels VMs
--skip-vm-utm	Skip UTM VMs
--skip-vm-vmware	Skip VMware Fusion VMs

Scan Subcommand

The scan subcommand provides targeted item-level scanning. Unlike the root command (which enters interactive mode by default), scan requires explicit flags and supports targeting individual items.

# Scan only npm and yarn caches
mac-cleaner scan --npm --yarn --dry-run

# Scan all developer caches plus Safari
mac-cleaner scan --dev-caches --safari

# Scan everything except Docker
mac-cleaner scan --all --skip-docker

# Output as JSON for automation
mac-cleaner scan --npm --json

Run mac-cleaner scan --help for the full list of targeted flags grouped by category.

License

MIT

Built With

This project was built using Claude Code and the Get Shit Done plugin.