🧹 cleanmac

macOS cleanup tool · Dry-run first · AI-native MCP integration

·

---

🚀 TL;DR

# 🧪 Safe preview
python3 cleanmac.py --json clean inspect --categories trash,mails,xcode --limit 10

# 🤖 AI tool definitions (24 tools)
python3 cleanmac.py --json ai-tools --format anthropic | jq '.tools | keys'

# 🧭 Safe workflow (recommended AI entry)
python3 cleanmac.py --json workflow --categories trash,downloads --dry-run-scope selected

# 🛡️ AI governance release gate
make ai-governance-smoke

# 🛡️ Sandbox execution
python3 cleanmac.py --root /tmp/sandbox --home /Users/tester clean run --categories trash --execute

🛡️ Safety principle: Nothing deleted by default. clean run is always a dry-run; only explicit --execute triggers deletion. High-risk categories require --yes. Live root / requires --allow-live-root.

---

✨ Highlights

🏷️	Description
🧹 Dry-run first	All cleanup commands preview only, no files deleted
🤖 AI-native · 24 tools	Full tool definitions in Anthropic / OpenAI / MCP formats
🏗️ MCP Server	Built-in Model Context Protocol stdio server
🔐 Multi-layer safety	Bundle protection, budgets, Trash recovery, confirmation tokens
🛡️ AI governance gates	Machine-readable LLM policy, release smoke, anti-pattern checks
🧪 Sandbox mode	--root / --home path remapping for safe testing
📦 Zero deps	Pure Python 3.10+, no external packages required

---

📖 Documentation

Guide	Link
📗 English — full CLI reference, safety model, AI/MCP patterns, development	docs/doc/README.md
📕 中文 — 完整命令参考、安全模型、AI/MCP 调用姿势、开发验证	docs/doc/README.CN.md

---

🧩 Quick Index

• 🤖 AI Invocation Patterns
• 🏗️ MCP Server Setup
• 🛡️ Safety Model
• 📦 Installation
• ✅ Development & CI
• 📕 中文 AI 调用姿势
• 📕 中文 MCP 服务器配置

---

💻 Installation

# ▶️ Run directly
python3 cleanmac.py clean list

# 📥 Install as package
python3 -m pip install -e .
cleanmac list

Requires Python 3.10+

---

🔗 Links

• 📗 Full English Guide
• 📕 中文文档
• 🐛 Issues
• 🔒 Security Policy