This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine
Every developer who bought a base-model 256GB or 512GB MacBook knows this exact flavor of existential dread. 💻 Apple charges so much for extra RAM and SSD storage that you could literally buy a second-hand motorbike with the price difference. So you tell yourself: "Arre bhai, 512GB is plenty! I'll store everything in the cloud and keep my machine clean."
Then, 18 months into your developer journey, you are sitting with a cup of hot cutting chai ☕ at 2 AM, trying to git clone a repository or compile an Xcode build, and macOS throws the dreaded pop-up:
⚠️ "Your disk is almost full. Optimize storage to continue."
You open System Settings → Storage. And there it is: a giant, ominous, gray bar labeled "System Data" hogging 85 GB.
You open Finder, look into your Applications folder, and you think you keep your machine spotless. Whenever you're done with an app, you drag it to the Trash. Clean, right?
Spoiler alert: Dragging an app to the Trash does almost nothing.
The .app binary gets trashed, but all its invisible tentacles—gigabytes of cached media, Electron containers, local database files, orphaned settings, crash dumps, and daemon logs—quietly stay behind in ~/Library/Application Support, ~/Library/Caches, and ~/Library/Containers. Months turn into years. The app is dead and uninstalled, but its digital soul keeps wandering inside your SSD.
They are, in the most literal sense possible: Ghosts in the Machine. 👻
When Hacktoberfest announced Week 4: Ghost in the Machine, it felt like a calling. Instead of writing another generic prompt wrapper, I wanted to build something deeply personal, useful, and poetic: Ghost Files for Mac Deep Cleaner (v3.2.0).
It's an open-source macOS cleanup suite that uses open-weight local AI (running 100% on your own Mac via Ollama with models like llama3.2:1b, llama3.2:3b, or gemma3:4b) to track down orphaned app leftovers, analyze their digital remains, write a poignant, gentle haunting about why they're still lingering, and let you inspect every single byte before sending them to rest in the Trash. 🕊️
What I Built
Mac Deep Cleaner v3.2.0 with Ghost Files is a native-feeling, privacy-first storage analyzer and cleanup suite built specifically for macOS.
Instead of running an opaque, scary black-box shell script that blindly nukes your active developer configs, Ghost Files approaches digital leftovers with care, intelligence, and respect:
🔍 The Ghost Scanner: It scans 8 sensitive user Library directories, matching reverse-DNS bundle identifiers (
com.figma.Desktop,com.example.tradex, etc.) against currently installed apps, Homebrew casks, system applications, and active services. If an app no longer exists anywhere on your system, its orphaned directory is identified as a "Ghost".📖 Local AI Storyteller: Using open-weight models (
llama3.2orgemma), it analyzes the leftover's name, age, size, and file makeup to compose a brief, poetic "haunting" note for each ghost.🕵️ Ghost Inspector Drawer: Click on any ghost card, and a slide-out drawer appears with real extracted application icons, an AI summary of what the app was used for, a live file explorer showing every single plist and cache file inside the folder, and instant search links for Google, GitHub, and DuckDuckGo.
-
🔒 Safety-First Protection & 0% False Positives:
- Likely Safe (Green): Pure regenerable caches and temp logs.
- Review First (Amber): Application configs or project states that might contain user data.
-
Locked (Red Lock): Items with unverified ownership or developer tools (like
.vscodeextensions, CLI tools, Flutter prototype containers). These cannot be deleted accidentally—they require clicking "Review locked ghost", typingUNLOCKinto a confirmation dialog, and a separate Trash review step.
🕯️ The Cleanup History (Ofrenda): Inspired by the tradition of Día de los Muertos, every ghost moved to the Trash is preserved in a dignified "Cleanup History", complete with date, size freed, and a farewell note, which you can export as a Markdown report (
cleanup-history.md).🛡️ Zero Cloud Fallback & 100% On-Device Privacy: Every byte is scanned locally. The AI runs on
127.0.0.1:11434. No file paths, usernames, or filenames are ever sent to an external server.
📸 Demo & Screenshots
2. The Ghost Inspector Drawer (Local Intelligence + Web & GitHub Context)
Clicking on any card opens the detailed slide-out inspector drawer, giving you instant web intelligence and an interactive file tree:
Above: Clicking on an orphaned container leftover displays its application icon, a detailed AI explanation of its workflows, an interactive browser of files inside the directory, and one-click search buttons for Google, GitHub, and DuckDuckGo.
3. Consent-Driven Local AI Settings & Privacy Controls
No sneaky background daemons. The user is in 100% control of every installation, start, and model download step:
4. Cleanup History (Ofrenda)
A dignified record of what you let go:
Above: Successful moves to Trash are remembered in the Cleanup History, exportable anytime as a markdown report.
💻 Code
The entire codebase is free and open-source under the Apache-2.0 License:
NK2552003
/
Mac-Cleaner
Detects and removes leftover files from uninstalled apps, stale caches, crash reports, logs, and other system junk — safely, with multiple layers of protection and full undo support.
Mac Deep Cleaner
Reclaim gigabytes of disk space with confidence — the safest, smartest macOS storage analyzer and cleanup suite.
Mac Deep Cleaner v3.2.0 combines storage analysis, reviewed cleanup, system diagnostics, maintenance, Homebrew package management, and external-disk management in a local dashboard, native macOS app, and command-line tools. File cleanup uses Trash by default; disk formatting and selected maintenance commands are permanent and require a separate review.
Version 3.2.0 adds a dedicated Homebrew manager with dependency explanations, groups, reverse trees, size rankings, update checks, services, and reviewed maintenance. Disks & volumes now hides recovery/system records by default and uses one scrolling page.
# Three convenient commands, same powerful tool
mac-deep-cleaner # Standard entrypoint
mac-cleaner # Alias
mdc # Fast CLI shorthand
Key Highlights
| Safety First | Modern UI & Desktop App | Deep Local Analysis |
|---|---|---|
| Never deletes without review | Responsive dashboard with dark-minimal aesthetic | Intelligent application footprints & leftovers |
| Finder Trash protection |
- 📦 Repository: github.com/NK2552003/Mac-Cleaner
- 🚀 PyPI Package:
pip install mac-deep-cleaner - 👻 Ghost Files Core Logic:
mac_deep_cleaner/ghosts/ - 🖥️ Desktop Swift Chrome: DOwnload the Zip from github release v3.2.0
🧠 How I Built It
Building a tool that touches a user's ~/Library directory requires extreme engineering discipline. If a web app crashes, you just refresh the browser. But if a disk cleaner script makes a mistake and deletes the wrong folder, someone's Xcode certificates, Docker volumes, or Git repositories disappear forever. 😱
Here is how the architecture works under the hood:
1. The Open-Weight AI Stack (Ollama + Llama 3.2 & Gemma)
I integrated Ollama via local loopback HTTP calls (http://127.0.0.1:11434):
- 🪶 Lightweight Inference: I recommend
llama3.2:1b(1.3 GB) for Macs with 8GB RAM,llama3.2:3bfor balanced speed, orgemma3:4bfor richer narration. - 🔒 Strict Privacy Sandboxing: The prompt sent to the model is carefully structured and anonymized. I never pass raw file paths, usernames, or personal file contents to the LLM. Only abstract metadata (
app_name,bundle_id,age_in_days,size_formatted,folder_kind) is provided:
# From mac_deep_cleaner/ghosts/llm.py
prompt = f"""You are a sensitive observer of forgotten digital things on macOS.
You will receive JSON describing an orphaned file leftover from an uninstalled app.
Compose a single poignant sentence describing how this leftover lingers on the system.
JSON input:
{{"name": "{ghost.name_guess}", "kind": "{ghost.kind}", "age_days": {ghost.age_days}, "size": "{ghost.size_fmt}"}}
"""
2. Safety Gating: The Model Can Only Add Caution, Never Remove It
In traditional AI applications, people worry about hallucinations causing damage. Here, I implemented a one-way ratchet rule:
- If our deterministic scanner classifies a folder as
LockedorReview First, the AI is mathematically forbidden from downgrading it toLikely Safe. - The AI can increase caution (e.g. noticing that a folder might contain user notes and recommending extra review), but it can never bypass safety locks.
3. Consent-Driven Lifecycle & Resource Management
Nobody likes an app that secretly starts background daemons or fills up their SSD with surprise 5GB downloads.
- Ghost Files is off by default.
- When enabling AI narration, a dedicated setup wizard checks available RAM and free storage.
- Every step requires an explicit, unchecked checkbox:
-
[ ] Install Ollama(via Homebrew if installed, or official app into~/Applications) [ ] Start Ollama server on 127.0.0.1:11434[ ] Download model (e.g. llama3.2:1b)
-
- If the user quits Mac Deep Cleaner, any Ollama child process started by the session is gracefully stopped.
- There is a one-click "Remove AI components" button that purges only the models and files that Mac Deep Cleaner installed.
4. Fast, Zero-Lag Native Webview Architecture
Rather than packaging a heavy 300MB Electron wrapper, Mac Deep Cleaner uses a hybrid approach:
- A lightweight Python engine handling filesystem scanning, bundle inspection, and local API routing.
- A native Swift macOS shell (
desktop/window_chrome.swift) utilizing WebKit with direct AppleScript bridges for native Finder interaction (revealInFinder,moveToTrash). - Pagination rendering (10 cards at a time) with virtualized DOM updates, ensuring silky-smooth 60fps scrolling even when there are hundreds of ghost leftovers.
🌍 Why Does Open Innovation Matter?
Let's be completely real: This project could not exist with proprietary, closed APIs.
If I had used an API like OpenAI, Claude, or Gemini:
🔐 The Privacy Catastrophe: To ask a cloud API about a leftover folder, I would have to transmit application identities, bundle names, and file patterns over the public internet. On a developer's machine, your library folder contains proprietary client names, internal company tools, and private repository IDs. Nobody in their right mind would run a disk cleaner that phones home to a cloud server with that data.
✈️ Offline-First Reality: A system maintenance utility should work on an airplane, in a remote cabin, or on a train with spotty Wi-Fi. Open-source local models don't need an internet connection to think.
💸 Zero API Cost Anxiety: Running a scan across 60 forgotten apps shouldn't cost \$0.05 in API tokens or fail because someone hit a monthly rate limit or forgot to recharge their billing account.
🗽 True Ownership: When you use open weights, the software belongs to you. No sudden terms-of-service changes, no deprecated API versions, no surprise subscription paywalls.
Open innovation made it possible to turn an everyday developer headache into an intimate, secure, on-device experience that respects the user's hardware and boundaries.
✨ The Spirit of It
There is something strangely nostalgic about scanning an old Mac. 🥹
While testing Ghost Files on my own MacBook, the scanner brought up a leftover folder: com.example.tradex. Untouched for 210 days.
It was a Flutter project I had hacked together last year during a weekend hackathon with a college friend. I was drinking cutting chai at 2 AM, arguing about state management, laughing about broken WebSocket feeds, dreaming about building our own fintech startup. The project never went to production. The app was deleted months ago.
Seeing that tiny 29KB container sitting in ~/Library/Containers felt like finding an old polaroid photo tucked inside a forgotten college notebook. 📸
The local AI wrote:
"A prototype trading application left behind, like an unfinished sketch on a whiteboard."
I didn't immediately delete it. I clicked Let it rest.
And that's the beauty of it. Technology isn't just cold bytes and silicon; it's a record of what I was trying to build, who I was spending our nights with, and where our curiosity took us. When you finally do decide to clean it up, sending it to the Trash with a small record in your Cleanup History feels like giving your machine a clean breath of fresh air. 🍃
🚀 What's New in Version 3.2.0 (The 3.x Evolution)
This release brings together our major 3.x desktop evolution, including:
👻 Ghost Files Engine: Intelligent discovery of abandoned app leftovers across 8 Library roots with 0% false positives for developer and CLI tools.
🤖 Local AI Storyteller: 100% on-device narration powered by Ollama (
llama3.2:1b,llama3.2:3b,gemma3:4b) with zero cloud telemetry.🔍 Ghost Inspector Drawer: Live folder hierarchy inspection, size breakdown, and one-click DuckDuckGo/GitHub web search context.
⚡ Performance & Pagination: 10-item virtualized pagination avoiding high CPU load during massive storage scans.
🍺 Homebrew Workspace: Dependency explanations, reverse dependency trees, size rankings, and two-stage safe Tidy workflow.
💾 External Disks & Volumes Toolkit: Guarded external drive management, APFS inventory, and volume tools.
🎨 Refined macOS UI: Native Swift window chrome, sticky cleanup history panel, and seamless dark/light mode toggle with full-screen support.
🛡️ Trash-First Safety: Multi-layer confirmation gates with typed phrase verification (
UNLOCK) for locked items before moving to Trash.
🏆 Prize Categories
I am submitting Mac Deep Cleaner: Ghost Files for:
🏆 Ghost in the Machine (Grand Theme): Reinterpreting abandoned app leftovers as lingering ghosts and using local open-weight AI to uncover their history and safely banish them.
🤖 Best Open-Weight / Local AI Application: Real-world, offline, private AI integration via Ollama without relying on cloud APIs.
🛠️ Best Developer Tool / System Utility: Empowering developers to reclaim precious SSD storage on macOS safely.
Built with ❤️, Python, Swift, and open-source AI by Nitish Kumar.
If you find this useful or relate to the 256GB Mac struggle, feel free to star the repo on GitHub! ⭐
Top comments (1)
it really did helped a lot! thanks man