Mac Disk Space Cleaner

An interactive terminal UI for analyzing and safely reclaiming disk space on macOS. Browse your filesystem by folder size, read built-in safety hints before you delete anything, and copy paths to the clipboard — all without leaving the terminal.

---

Features

• Size-sorted directory listing — see what's eating your disk at a glance; sizes are computed in the background while you browse
• Built-in safety database — every folder is classified and explained before you act:

  Badge	Level	Meaning
  🚫 CRITICAL	System files	Removing will permanently break macOS
  ⚠️ DANGER	Important data	Significant risk — review carefully
  ⚡ CAUTION	User data / envs	Think before removing
  ✅ SAFE	Caches / build artifacts	Safe to remove, auto-regenerated
  ❓ UNKNOWN	No rule found	Inspect contents before acting

• Safe deletion — a full confirmation dialog with size, safety level, and hint before anything is removed
• One-click copy — copy a folder's name or full path to the clipboard
• Navigate freely — drill into subdirectories, jump home, or go back up; supports system folders too (sudo python cleaner.py / for full sizes)
• Symlink aware — symlinks are displayed separately (🔗) and cannot be accidentally deleted via rmtree
• Race-condition safe — fast navigation never lets a slow background scan overwrite what you're currently viewing

---

Requirements

• macOS (uses pbcopy for clipboard and du for fast directory sizing)
• Python 3.9+
• Textual ≥ 0.30.0

---

Installation

# 1. Clone the repository
git clone https://github.com/xnimax/mac-disk-cleaner.git
cd mac-disk-cleaner

# 2. Install the dependency (only one)
pip install -r requirements.txt

# 3. Run
python cleaner.py

Tip: To see system folder sizes (e.g. /Library, /Applications), run with sudo:

sudo python cleaner.py /

---

Usage

python cleaner.py                  # Start in your home directory
python cleaner.py ~/Downloads      # Start in a specific folder
python cleaner.py /                # Browse from the filesystem root
sudo python cleaner.py /           # Full system scan with accurate sizes

Keyboard shortcuts

Key	Action
↑ / ↓	Move selection
Enter	Open selected directory
→	Open selected directory
← / Backspace	Go up one level
H	Jump to home directory
S	Toggle sort (size ↔ name)
C	Copy full path to clipboard
N	Copy folder name to clipboard
D	Delete selected directory (with confirmation)
R	Refresh / rescan current directory
Q	Quit

Inside the Delete confirmation dialog:

Key	Action
Y	Confirm deletion
N / Esc	Cancel

---

Safety database

The safety database covers the most common macOS locations, including:

• System trees — /System, /usr, /bin, /sbin, /private, /dev
• User Library — ~/Library/Caches (SAFE), ~/Library/Keychains (CRITICAL), ~/Library/Developer/Xcode/DerivedData (SAFE, often 10–50 GB), and more
• JavaScript — node_modules, .npm, .pnpm-store, .next, .nuxt, .turbo, …
• Python — __pycache__, venv, .venv, .tox, .pytest_cache, .mypy_cache, …
• JVM / mobile — .gradle, .m2, target, Pods, .cocoapods
• Ruby — .bundle, .rbenv
• Version control — .git (DANGER), .svn
• Runtime managers — .nvm, .pyenv

Missing a path? See Contributing.

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

Areas where help is especially valuable:

• Safety database entries — new macOS paths, package managers, build tools
• Bug reports — especially around edge cases: unusual permissions, network mounts, non-standard macOS setups
• Compatibility — testing on different macOS versions or Python releases

---

License

MIT © xnimax — see LICENSE for the full text.