clean-my-mac
Safe, staged macOS disk cleanup for AI agents & developers. Recovers GBs from Xcode, Docker, node_modules, AI models, and caches with dry-ru
Open source Open in the app JSON README (API)
About
Safe, staged macOS disk cleanup for AI agents & developers. Recovers GBs from Xcode, Docker, node_modules, AI models, and caches with dry-run safety.
Details
- Kind
- Plugins
- Topic
- Cloud & DevOps
- Publisher
- shihabshahrier
- Origin
- gemini
- Category
- ferramentas
- Version
- 1.0.0
- Last push
- 2026-06-12T23:45:14Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
shihabshahrier/clean-my-mac
README
# clean-my-mac 🧹
> ⚡ **Safe, staged macOS disk cleanup for developers and AI coding agents.** Recover GBs of storage from Xcode, Docker, node_modules, AI models, and system caches with 100% dry-run safety.
**clean-my-mac** is an intelligent, agent-compatible macOS utility designed to safely reclaim disk space from developer environments (such as Xcode DerivedData, Docker volumes, npm/pnpm/yarn caches, and Hugging Face AI models) and system cache bloat. Every cleanup action is profiled, previewed in a dry-run, and requires explicit per-phase confirmation.
---
## Agent Support
| Agent | Invocation | Install |
|-------|-----------|---------|
| Claude Code | `/clean-my-mac` or natural language | `claude plugin install clean-my-mac` |
| Cursor | `/clean-my-mac` | `.cursor/rules/clean-my-mac.mdc` (included) |
| Windsurf | `/clean-my-mac` | `.windsurf/rules/clean-my-mac.md` (included) |
| Cline | `/clean-my-mac` | `.clinerules/clean-my-mac.md` (included) |
| GitHub Copilot | natural language | `.github/copilot-instructions.md` (included) |
| Codex | `/clean-my-mac` | `.codex/config.toml` (included) |
| Gemini CLI | `/clean-my-mac` | `gemini-extension.json` (included) |
| Amp / Goose / opencode | `/clean-my-mac` | `bash install.sh` |
---
## What It Cleans
| Target | Risk | Notes |
|--------|------|-------|
| User & System Caches | 🟢 Low | Auto-regenerated by macOS |
| Logs & Trash | 🟢 Low | Always regenerated |
| Homebrew cache | 🟢 Low | `brew cleanup` re-downloads on demand |
| npm / pnpm / yarn caches | 🟢 Low | Rebuilt on next install |
| Xcode DerivedData | 🟢 Low | Rebuilt on next build |
| iOS Simulators | 🟡 Medium | Re-downloadable from Xcode |
| Docker images | 🟡 Medium | Re-pullable from registry |
| node_modules | 🟡 Medium | Listed only — you choose |
| Time Machine snapshots | 🟡 Medium | Backup confirmation required |
| AI model files | 🔴 High | Listed only — you choose |
| Xcode Archives | 🔴 High | Double confirmation required |
| iOS Device Backups | 🔴 High | Guided to Finder only, never scripted |
Typical recovery on a 256 GB M1 Mac:
- Light developer: **5–15 GB**
- Active Xcode dev: **20–60 GB**
- Docker + Xcode + AI models: **30–100+ GB**
---
## Install
### All agents at once
```bash
git clone https://github.com/shihabshahrier/clean-my-mac.git
cd clean-my-mac
bash install.sh
```
### Claude Code (plugin)
```bash
claude plugin install shihabshahrier/clean-my-mac
```
Or from local clone:
```bash
claude plugin marketplace add /path/to/clean-my-mac
claude plugin install clean-my-mac
```
### Manual (any agent)
```bash
git clone https://github.com/shihabshahrier/clean-my-mac.git
mkdir -p ~/.claude/skills/clean-my-mac
cp -r clean-my-mac/skills/clean-my-mac/. ~/.claude/skills/clean-my-mac/
```
---
## Usage
In any supported agent, say:
```
"My Mac only has 20 GB left, help me clean it up"
"Free up disk space"
"Clean my Mac safely"
"What's taking up all my storage?"
```
Or invoke directly: `/clean-my-mac`
---
## How It Works
```
Phase -1 → Profile user (active tools, backup status, what to protect)
Phase 0 → Analyze disk — zero deletions, full size breakdown
Phase 1 → Safe caches & logs [LOW]
Phase 2 → Developer tools [LOW–MED]
Phase 3 → Docker [MEDIUM]
Phase 4 → AI model files [HIGH — list only]
Phase 5 → Time Machine snapshots [MEDIUM — backup confirmed first]
Phase 6 → Large file review [USER-DECIDES]
Phase 7 → iCloud optimization [guidance only]
→ Final report
```
Every phase: profile check → dry-run preview → confirmation → execution.
---
## File Structure
```
clean-my-mac/
├── skills/clean-my-mac/
│ ├── SKILL.md ← Skill definition (source of truth)
│ ├── scripts/
│ │ ├── analyze_storage.sh ← Phase 0: disk analysis
│ │ ├── cleanup_caches.sh ← Phase 1: caches, logs, trash
│ │ ├── cleanup_homebrew.sh ← Phase 2: Homebrew
│ │ ├── cleanup_xcode.sh ← Phase 2: Xcode artifacts
│ │ ├── cleanup_node.sh ← Phase 2: Node.js ecosystem
│ │ ├── cleanup_docker.sh ← Phase 3: Docker
│ │ └── cleanup_snapshots.sh ← Phase 5: Time Machine snapshots
│ ├── config/
│ │ ├── protected_paths.txt ← Never-delete list
│ │ └── safe_cleanup_rules.json ← Rules per category
│ └── reference/
│ ├── safe-paths.md
│ ├── dangerous-paths.md
│ ├── cleanup-strategies.md
│ └── macos-storage-guide.md
├── .claude-plugin/ ← Claude Code plugin manifest
├── .cursor/rules/ ← Cursor rules
├── .windsurf/rules/ ← Windsurf rules
├── .clinerules/ ← Cline rules
├── .codex/ ← Codex config
├── agents/openai.yaml ← Codex display config
├── .github/copilot-instructions.md ← Copilot instructions
├── AGENTS.md ← Codex / Amp / Goose context
├── GEMINI.md ← Gemini CLI context
├── gemini-extension.json ← Gemini CLI extension
└── install.sh ← Install to all agent paths
```
---
## Security
- `allowed-tools` restricts Claude to: `Bash`, `Read`, `Glob`, `Grep`, `Write`
- No network access during cleanup
- `config/protected_paths.txt` checked before every deletion
- Scripts use `set -euo pipefail` — fail fast on errors
- All operations logged to `~/clean-my-mac-log-<date>.txt`
- Every script supports `--dry-run` mode
- HIGH-risk operations require double confirmation
- iOS Device Backups: guided to Finder only, never scripted
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). Read [CLAUDE.md](CLAUDE.md) first.
---
📖 **Project page:** https://shihub.online/projects/clean-my-mac