{
  "markdown": "# clean-my-mac 🧹\n\n> ⚡ **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.\n\n**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.\n\n---\n\n## Agent Support\n\n| Agent | Invocation | Install |\n|-------|-----------|---------|\n| Claude Code | `/clean-my-mac` or natural language | `claude plugin install clean-my-mac` |\n| Cursor | `/clean-my-mac` | `.cursor/rules/clean-my-mac.mdc` (included) |\n| Windsurf | `/clean-my-mac` | `.windsurf/rules/clean-my-mac.md` (included) |\n| Cline | `/clean-my-mac` | `.clinerules/clean-my-mac.md` (included) |\n| GitHub Copilot | natural language | `.github/copilot-instructions.md` (included) |\n| Codex | `/clean-my-mac` | `.codex/config.toml` (included) |\n| Gemini CLI | `/clean-my-mac` | `gemini-extension.json` (included) |\n| Amp / Goose / opencode | `/clean-my-mac` | `bash install.sh` |\n\n---\n\n## What It Cleans\n\n| Target | Risk | Notes |\n|--------|------|-------|\n| User & System Caches | 🟢 Low | Auto-regenerated by macOS |\n| Logs & Trash | 🟢 Low | Always regenerated |\n| Homebrew cache | 🟢 Low | `brew cleanup` re-downloads on demand |\n| npm / pnpm / yarn caches | 🟢 Low | Rebuilt on next install |\n| Xcode DerivedData | 🟢 Low | Rebuilt on next build |\n| iOS Simulators | 🟡 Medium | Re-downloadable from Xcode |\n| Docker images | 🟡 Medium | Re-pullable from registry |\n| node_modules | 🟡 Medium | Listed only — you choose |\n| Time Machine snapshots | 🟡 Medium | Backup confirmation required |\n| AI model files | 🔴 High | Listed only — you choose |\n| Xcode Archives | 🔴 High | Double confirmation required |\n| iOS Device Backups | 🔴 High | Guided to Finder only, never scripted |\n\nTypical recovery on a 256 GB M1 Mac:\n- Light developer: **5–15 GB**\n- Active Xcode dev: **20–60 GB**\n- Docker + Xcode + AI models: **30–100+ GB**\n\n---\n\n## Install\n\n### All agents at once\n```bash\ngit clone https://github.com/shihabshahrier/clean-my-mac.git\ncd clean-my-mac\nbash install.sh\n```\n\n### Claude Code (plugin)\n```bash\nclaude plugin install shihabshahrier/clean-my-mac\n```\n\nOr from local clone:\n```bash\nclaude plugin marketplace add /path/to/clean-my-mac\nclaude plugin install clean-my-mac\n```\n\n### Manual (any agent)\n```bash\ngit clone https://github.com/shihabshahrier/clean-my-mac.git\nmkdir -p ~/.claude/skills/clean-my-mac\ncp -r clean-my-mac/skills/clean-my-mac/. ~/.claude/skills/clean-my-mac/\n```\n\n---\n\n## Usage\n\nIn any supported agent, say:\n```\n\"My Mac only has 20 GB left, help me clean it up\"\n\"Free up disk space\"\n\"Clean my Mac safely\"\n\"What's taking up all my storage?\"\n```\n\nOr invoke directly: `/clean-my-mac`\n\n---\n\n## How It Works\n\n```\nPhase -1  →  Profile user (active tools, backup status, what to protect)\nPhase  0  →  Analyze disk — zero deletions, full size breakdown\nPhase  1  →  Safe caches & logs          [LOW]\nPhase  2  →  Developer tools             [LOW–MED]\nPhase  3  →  Docker                      [MEDIUM]\nPhase  4  →  AI model files              [HIGH — list only]\nPhase  5  →  Time Machine snapshots      [MEDIUM — backup confirmed first]\nPhase  6  →  Large file review           [USER-DECIDES]\nPhase  7  →  iCloud optimization         [guidance only]\n           →  Final report\n```\n\nEvery phase: profile check → dry-run preview → confirmation → execution.\n\n---\n\n## File Structure\n\n```\nclean-my-mac/\n├── skills/clean-my-mac/\n│   ├── SKILL.md                     ← Skill definition (source of truth)\n│   ├── scripts/\n│   │   ├── analyze_storage.sh       ← Phase 0: disk analysis\n│   │   ├── cleanup_caches.sh        ← Phase 1: caches, logs, trash\n│   │   ├── cleanup_homebrew.sh      ← Phase 2: Homebrew\n│   │   ├── cleanup_xcode.sh         ← Phase 2: Xcode artifacts\n│   │   ├── cleanup_node.sh          ← Phase 2: Node.js ecosystem\n│   │   ├── cleanup_docker.sh        ← Phase 3: Docker\n│   │   └── cleanup_snapshots.sh     ← Phase 5: Time Machine snapshots\n│   ├── config/\n│   │   ├── protected_paths.txt      ← Never-delete list\n│   │   └── safe_cleanup_rules.json  ← Rules per category\n│   └── reference/\n│       ├── safe-paths.md\n│       ├── dangerous-paths.md\n│       ├── cleanup-strategies.md\n│       └── macos-storage-guide.md\n├── .claude-plugin/                  ← Claude Code plugin manifest\n├── .cursor/rules/                   ← Cursor rules\n├── .windsurf/rules/                 ← Windsurf rules\n├── .clinerules/                     ← Cline rules\n├── .codex/                          ← Codex config\n├── agents/openai.yaml               ← Codex display config\n├── .github/copilot-instructions.md  ← Copilot instructions\n├── AGENTS.md                        ← Codex / Amp / Goose context\n├── GEMINI.md                        ← Gemini CLI context\n├── gemini-extension.json            ← Gemini CLI extension\n└── install.sh                       ← Install to all agent paths\n```\n\n---\n\n## Security\n\n- `allowed-tools` restricts Claude to: `Bash`, `Read`, `Glob`, `Grep`, `Write`\n- No network access during cleanup\n- `config/protected_paths.txt` checked before every deletion\n- Scripts use `set -euo pipefail` — fail fast on errors\n- All operations logged to `~/clean-my-mac-log-<date>.txt`\n- Every script supports `--dry-run` mode\n- HIGH-risk operations require double confirmation\n- iOS Device Backups: guided to Finder only, never scripted\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Read [CLAUDE.md](CLAUDE.md) first.\n\n---\n\n📖 **Project page:** https://shihub.online/projects/clean-my-mac\n",
  "bytes": 5810,
  "sha": "189ffda6c057eb9f465862ea9b92deb3cb4e5c2278087cf1c72c8e5cf0beeeb6",
  "repo_slug": "shihabshahrier/clean-my-mac",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_shihabshahrier_clean_my_mac_46330d1a/readme"
}