What is the clean-my-mac skill?

clean-my-mac is an AI agent skill by Shahriar Labs that safely analyzes macOS disk usage and recovers GBs of storage across 7 staged phases — covering Xcode DerivedData, Docker images, npm caches, node_modules, Homebrew, logs, and Time Machine snapshots. It always dry-runs before deleting.

Is it safe? Will it delete important files?

clean-my-mac uses a protected_paths list and always dry-runs each phase before asking for deletion approval. It checks for active tools (running Docker containers, active npm workspaces) before touching related caches. Active project node_modules are never deleted.

How much disk space can it recover?

On a typical developer Mac with 6+ months of active use, clean-my-mac typically recovers 20–80 GB. The biggest gains come from Xcode DerivedData (5–30 GB), Docker unused images (5–40 GB), and node_modules in inactive projects (varies widely).

Does clean-my-mac work on Apple Silicon?

Yes. clean-my-mac is optimized for Apple Silicon (M1/M2/M3/M4) Macs but works on Intel Macs too. It checks the correct Homebrew prefix for each architecture.

clean-my-mac: Safe Disk Cleanup for Dev Teams

clean-my-mac is a staged, dry-run-safe macOS cleanup skill that recovers GBs of storage from Xcode, Docker, caches, and node_modules — without ever deleting files without approval. Built by Shahriar Labs for the developer workflow: it understands active tools, respects running processes, and treats every cleanup phase as reversible until confirmed.

The 7-Phase Cleanup Model

clean-my-mac profiles your system first — installed tools, active processes, disk usage by directory — then runs 7 cleanup phases in safety-priority order:

System caches: ~/Library/Caches, /Library/Caches, Safari/Chrome caches. Safe to clear fully.
Logs: ~/Library/Logs, /var/log rotated logs. Compresses before deleting old entries.
Xcode DerivedData: Biggest single-tool win. Checks no Xcode build is running before wiping.
npm/yarn/pnpm caches: Package manager caches. Rebuilds automatically on next install.
node_modules: Only in inactive projects (no active git activity in 30+ days). Never touches active workspaces.
Docker: Stopped containers, dangling images, unused volumes. Checks no containers are running first.
Time Machine local snapshots: APFS local snapshots older than 7 days. Last phase, requires explicit confirmation.

Dry-Run First, Always

Every phase shows you what would be deleted and how much space it recovers before touching anything. You approve each phase individually. This is the opposite of aggressive cleanup tools that delete first and ask questions never.

On Apple Silicon Macs with 256 GB SSDs — the most constrained developer setup — clean-my-mac typically recovers 30–60 GB on a first run. That's the difference between a machine that swap-thrashes during builds and one that doesn't.

Frequently Asked Questions

What is the clean-my-mac skill?: An AI skill that recovers GBs of macOS storage across 7 staged phases with dry-run preview and per-phase approval.
Is it safe?: Yes — dry-runs before every deletion, respects active tools, never touches active project node_modules.
How much space can it recover?: Typically 20–80 GB on developer Macs with 6+ months of active use.
Does it work on Apple Silicon?: Yes — optimized for M1/M2/M3/M4, works on Intel too.

Written by Shihab Shahriar Antor — AI Engineer & Founder of Shahriar Labs. Building LetX, QuantumSketch, and open-source AI agent skills.

clean-my-mac: Safe Disk Cleanup for Dev Teams

The 7-Phase Cleanup Model

Dry-Run First, Always

Frequently Asked Questions

Related Articles

softco: Turn AI Agents Into a Software Firm

skill-builder: Build AI Agent Skills From Plain English