🩺 macdoctor

A safe, interactive storage analyzer and cleaner for macOS developers.

---

Features

Feature	Details
Storage Analysis	Scans ~/Library, Application Support, Developer and shows the top 10 largest folders
Smart Detection	Warns when VS Code, Xcode, iOS Simulators, Android, or Docker exceed 5 GB
Interactive Menu	Step-by-step cleanup with a y/n confirmation before any deletion
Dry-run Mode	Preview exactly what would be deleted, without touching anything
Safety Guardrails	Only deletes known-safe directories (caches, logs, DerivedData, simulators)
Zero dependencies	Pure bash — no Homebrew, no Python, no npm

---

Installation

# Clone or download the repo
git clone <repo-url>
cd macdoctor

# Make files executable
chmod +x macdoctor install.sh

# Install to /usr/local/bin (requires sudo)
./install.sh

After installation, run from anywhere:

macdoctor

---

Usage

macdoctor [options]

Options:
  --dry-run, -n    Preview what would be deleted (no actual deletion)
  --version, -v    Print version and exit
  --help, -h       Print usage and exit

Normal run

macdoctor

1. Scans your ~/Library and shows disk usage.
2. Warns about any developer tools using more than 5 GB.
3. Presents an interactive menu:

  1.  Clean VS Code cache
  2.  Clean Xcode DerivedData & Archives
  3.  Remove iOS Simulators
  4.  Clean Android AVD
  5.  Run all cleanups
  q.  Exit

Each action asks for confirmation before deleting anything.

Dry-run mode

macdoctor --dry-run

Runs the full scan and shows every path that would be deleted — nothing is actually removed. Safe to run at any time.

---

What Gets Deleted

macdoctor only removes directories it knows are safe to delete. User projects and system files are never touched.

Cleanup	Paths removed
VS Code cache	~/Library/Application Support/Code/Cache
	~/Library/Application Support/Code/CachedData
	~/Library/Application Support/Code/CachedExtensionVSIXs
	~/Library/Application Support/Code/GPUCache
	~/Library/Application Support/Code/logs
	~/Library/Application Support/Code/Crashpad
Xcode	~/Library/Developer/Xcode/DerivedData
	~/Library/Developer/Xcode/Archives (confirms separately)
iOS Simulators	Unavailable runtimes via xcrun simctl delete unavailable
	All device data via xcrun simctl erase all (optional)
Android	~/.android/cache
	~/.android/avd/<name>/ (prompts per AVD)

What is NEVER deleted

• Your source code or projects
• VS Code extensions or settings
• Xcode application itself
• System files outside ~/Library
• Any directory not in the explicit whitelist

---

Output Example

══════════════════════════════════════════════
  🩺  macdoctor  v1.0.0
══════════════════════════════════════════════

▸ 🔍 Scanning ~/Library...

  ~/Library                               82G
  ~/Library/Application Support           45G
  ~/Library/Developer                     30G

▸ 📊 Top 10 Largest Folders in ~/Library

  ★ 30G  ~/Library/Developer              ← biggest
  2.  22G  ~/Library/Application Support/Code
  3.  12G  ~/Library/Caches
  ...

▸ 🧠 Smart Detection

⚠️   VS Code is using 22G
⚠️   Xcode is using 18G
     iOS Simulators             4.2G
     Docker                     3.1G

▸ 🛠  Cleanup Menu

  1.  Clean VS Code cache
  2.  Clean Xcode DerivedData & Archives
  3.  Remove iOS Simulators
  4.  Clean Android AVD
  5.  Run all cleanups
  q.  Exit

Enter choice: 1

Clean VS Code cache? (y/n) y
⠸ Removing VS Code/Cache (1.2G)...
✅  Removed VS Code/Cache  (1.2G freed)
✅  VS Code cache cleaned.

---

Requirements

• macOS (any recent version)
• bash 3.2+ (pre-installed on macOS)
• xcrun / Xcode command-line tools (only needed for Simulator cleanup)

---

Uninstall

sudo rm /usr/local/bin/macdoctor

---

License

MIT