🧹 MacClean AI

AI-powered Mac disk cleaner. Scan smarter, clean faster.
Built with Python + Groq AI · macOS native look · No subscription required

---

⬇️ How to Download & Open (No Technical Experience Needed)

You don't need to know how to code. Just follow the steps below.

---

Step 1 — Download the App

1. Look on the right side of this page for the "Releases" section

2. Click on the latest release (e.g. MacClean AI v1.0.0)

3. Click on MacClean-AI-v1.0.zip to download it

   Or go directly to: github.com/crisgea71/macclean-ai/releases

---

Step 2 — Install & Open the App

1. Go to your Downloads folder
2. Double-click MacClean-AI-v1.0.zip — it unzips automatically
3. You'll see MacClean AI.app (broom icon)
4. Drag it into your Applications folder (just like any other app)

---

⚠️ First-time setup — removing the macOS security block

macOS blocks apps downloaded from the internet by default. You need to do this once, right after moving the app to Applications.

Step 1 — Open Terminal

Press Command (⌘) + Space on your keyboard → type Terminal → press Enter

A window with a black or white background opens. That's Terminal — don't worry, you just need to paste one line.

Step 2 — Paste this command and press Enter

xattr -cr /Applications/"MacClean AI.app"

Copy the line above exactly, paste it into Terminal, and press Enter. Nothing will appear on screen after — that's normal, it means it worked ✅

Step 3 — Open the app

Go to your Applications folder and double-click MacClean AI.app. It will open normally, with no warning. You never need to do this again.

---

Why does this happen?
macOS automatically blocks apps that don't have a paid Apple Developer certificate ($99/year). The app is safe — the command above simply tells macOS to trust it on your computer.

---

Step 3 — Get a Free Groq API Key

MacClean AI uses AI features powered by Groq — a completely free service.

1. Go to console.groq.com
2. Create a free account (or sign in with Google)
3. Click "Create API Key", give it a name, and copy the key (it looks like: gsk_abc123...)
4. Open MacClean AI → click ⚙ Settings → paste the key in the Groq API Key field → Save

---

Step 4 — Use the App

1. Click "Choose Folder" and select a folder on your Mac (e.g. Downloads, Documents)
2. Click "Scan" — takes a few seconds, with a live progress counter
3. Review what the app found:
   • Duplicate files
   • Heavy folders (node_modules, .venv)
   • Cache and temp files
   • Old installers (.dmg, .pkg)
   • Old screenshots
   • Broken symlinks
4. Check the items you want to delete
5. Click "Delete Selected" and confirm

That's it. The AI explains what it found in plain English.

---

💡 Why Use MacClean AI?

Most people never clean their Mac because it's boring, slow, and risky — you don't know what's safe to delete.

With MacClean AI you just:

1. Pick a folder
2. Click Scan
3. Read what the AI found
4. Check what you want to delete
5. Click Delete Selected

No Terminal. No technical knowledge. No guessing.

---

🔒 Safety First

MacClean AI is built around one principle: you are always in control.

• ✅ Nothing is deleted automatically — every deletion requires your manual selection
• ✅ Confirmation dialog before any file is removed
• ✅ System folders are never touched — only the folder you choose gets scanned
• ✅ Large files and old files are info-only — shown but never pre-selected for deletion
• ✅ AI gives suggestions, not commands — final decision is always yours

---

⏱️ Time Saved vs. Doing It Manually

Task	Manual	MacClean AI
Find duplicate files	45–90 min	< 30 seconds
Hunt down old installers	20 min	< 10 seconds
Find & delete cache/temp files	30 min	< 10 seconds
Spot duplicate PDFs	60 min	< 30 seconds
Find broken symlinks	Impossible without Terminal	automatic
Find heavy node_modules/.venv	15 min	< 10 seconds
Total	~3 hours	⚡ under 2 minutes

---

✨ What It Finds

Category	What it finds	Deletable
🔁 Duplicate Files	Identical files taking up space twice	✅
📄 Duplicate PDFs	Same PDF saved in multiple locations	✅
📦 Old Installers	.dmg, .pkg, .exe you forgot about	✅
📸 Old Screenshots	Screenshots older than 1 day	✅ auto-selected
🗑 Cache & Temp	.DS_Store, __pycache__, .tmp	✅ auto-selected
🔗 Broken Symlinks	Dead links pointing to nothing	✅ auto-selected
⚠️ Heavy Folders	node_modules, .venv from old projects	✅
💾 Large Files	Files over 500 MB	👁 info only
🕐 Old Files	Not modified in 6+ months	👁 info only

---

🤖 AI Features (powered by Groq)

• Auto-summary — after every scan, AI explains what it found in simple terms
• Safe-to-delete suggestions — AI tells you what's risky and what's safe
• Chat assistant — ask anything: "What is pycache?", "Is this .dmg safe to delete?"
• Powered by llama-3.3-70b-versatile via Groq (free tier available)

---

💳 Free vs Pro

Feature	Free (2 scans)	Pro
All scan categories	✅	✅
AI summary & chat	✅	✅
Delete selected files	✅	✅
Unlimited scans	❌	✅

Pro → contact the developer for a license key

---

🛠 For Developers — Run from Source

# 1. Clone the repo
git clone https://github.com/crisgea71/macclean-ai.git
cd macclean-ai

# 2. Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Run
python3 main.py

---

🗂️ Project Structure

macclean-ai/
├── main.py          # UI + entry point (customtkinter)
├── scanner.py       # Scan logic (duplicates, cache, PDFs, symlinks...)
├── cleaner.py       # Delete logic
├── ai_engine.py     # Groq API integration
├── config.py        # API key + license/trial management
├── requirements.txt
└── dist/
    └── MacClean AI.app   # Packaged app

---

🛠 Tech Stack

Tool	Purpose
Python 3.11+	Core language
customtkinter	Modern UI
Groq SDK	AI integration
pathlib	File operations
PyInstaller	.app packaging

---

📄 License

Free for personal use · Pro license for unlimited scans
© 2025 MacClean AI — Built with ❤️ and AI