NK2552003

Finding the Real Ghosts in the Machine: How I Used Local Open-Source AI to Hunt Down Gigs of Dead App Leftovers on My Mac 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 !Image description 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: 1. 🔍 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". 2. 📖 Local AI Storyteller: Using open-weight models (llama3.2 or gemma), it analyzes the leftover's name, age, size, and file makeup to compose a brief, poetic "haunting" note for each ghost. 3. 🕵️ 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. 4. 🔒 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 .vscode extensions, CLI tools, Flutter prototype containers). These cannot be deleted accidentally—they require clicking "Review locked ghost", typing UNLOCK into a confirmation dialog, and a separate Trash review step. 5. 🕯️ 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). 6. 🛡️ 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 !Ghost Screen Displaying the ghosted files --- 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: !Ghost Analysis of the file using Open Weight model 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: !Image description --- 4. Cleanup History (Ofrenda) A dignified record of what you let go: !Image description 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: {% github NK2552003/Mac-Cleaner %} - 📦 Repository: 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:3b for balanced speed, or gemma3:4b for 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 Locked or Review First, the AI is mathematically forbidden from downgrading it to Likely 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: 1. [ ] Install Ollama (via Homebrew if installed, or official app into ~/Applications) 2. [ ] Start Ollama server on 127.0.0.1:11434 3. [ ] 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: 1. 🔐 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. 2. ✈️ 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. 3. 💸 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. 4. 🗽 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! ⭐

I Had No Idea What Was Eating My Mac’s Storage, So I Built Something to Show Me My Mac said 179.58 GB of 245.11 GB used. Applications made sense. Documents made sense. But a huge gray block labeled System Data took up more space than everything else combined, and macOS wouldn't tell me what was inside it. !Snapshot of my Disk !What the hack is this I got tired of guessing, so I decided to build something that would show me everything and let me act on it. The next few days looked a lot like this: !Image description How it came together The first version was a plain CLI, built with a bit of help from my friend, AI. !AI and Human Friend It worked, but only just. It listed files under 10 MB, had no color, and nothing was organized. So I went back and looked for libraries that could present the output properly, and rich was a big help. The second version was decent, but it still felt like something was missing. Next I wondered whether the output could be interactive. It turned out I could connect a web interface to the Python side and route everything through it. That was a real improvement, but still not quite there. A bit more digging showed me I could wrap that web interface in a native window. That's how it became a proper macOS app, which I built for myself first. Then I opened Mac Deep Cleaner, the tool I'd made for exactly this problem, and let it scan my own machine. It found a lot. More importantly, it showed me where every gigabyte lived, so I didn't have to guess. That's the whole idea: a cleaner that opens the box and lets you decide, instead of deleting things you never got to see. The one rule > Never delete anything the user hasn't reviewed. Everything else grew out of that sentence: - Files go to Finder's Trash, not straight into oblivion. - Before anything moves, every cleanup is checked against scan generation tokens, exact file IDs, inode matches, and path restrictions. - System files (com.apple.*, SIP-protected paths, running app bundles) are locked and can't be touched. - There's no cloud analytics. Everything runs on your machine. What the scan found on my Mac When you launch it, you get a local dashboard that tells you the truth right away. !Scan Result Across 68 items, it found 34.63 GB that could be reclaimed. The split underneath that headline number matters more: - Safe to remove: 41.39 MB - Review first: 32.90 GB - Needs care: 1.69 GB I could have made that headline far more exciting by auto-selecting everything. Instead, only the tiny safe slice is one click away. The big chunk is marked "Review first" because the tool can't know what matters to you, and I think that honesty is the whole point of the product. Seeing inside your apps The part I'm proudest of is the Application Analyzer. Pick any app and it shows the full footprint, not just the .app bundle. !Specific App Result Take VS Code, which uses 3.01 GB in total. The app bundle is 1.5 GB and Application Support is another 1.51 GB. The caches, the part that's truly regenerable, are only 2.28 MB. A lot of people assume clearing caches frees up gigabytes, and here you can see it doesn't. You get to decide with real numbers. It also notices when an app is running and tells you to quit it before uninstalling. It's a small detail, but it saves you from a bad afternoon. Under the hood For the curious: - The core is Python 3.9+, installable with pip install mac-deep-cleaner. - A local web dashboard is served on a loopback port. - A Swift window shell provides native macOS chrome and full-screen support. - Scanning is multi-threaded, with content hashing for duplicate detection. - One tool, three commands: mac-deep-cleaner, mac-cleaner, and mdc. What's new in v3.0.5 This release is all about polish, the things you only notice when they're wrong: - I fixed the missing top inset in browser mode, without disturbing native window and full-screen spacing. - The dashboard, favicon, README, and macOS icon now all use a single assets/app_icon.png, and I removed the redundant branding images. - Shared assets now ship in Python distributions and standalone macOS builds. - The CLI and native bundle versions come from one package version constant, so they can't drift apart. Installing it Option 1: Download the app (easiest) Grab Mac-Deep-Cleaner-macOS.zip (about 9.7 MB) from the v3.0.5 release page. !Mac Deep Cleaner app icon Unzip it and drag Mac Deep Cleaner.app into your /Applications folder. Each release asset shows a SHA-256 checksum, so you can verify your download: shasum -a 256 ~/Downloads/Mac-Deep-Cleaner-macOS.zip The output should match the checksum on the release page. Option 2: Install with pip pip install mac-deep-cleaner mdc Option 3: Build from source git clone https://github.com/NK2552003/Mac-Cleaner.git cd Mac-Cleaner python3 scripts/build_mac.py About the macOS warning The downloadable app isn't notarized by Apple yet, so macOS may tell you it's "damaged" or can't be opened. It isn't damaged. Gatekeeper is just being cautious about a downloaded app that hasn't been notarized. If you got it from the official release page, move it to /Applications and run: xattr -d com.apple.quarantine "/Applications/Mac Deep Cleaner.app" This only removes the download-quarantine flag from that one app. If you'd rather skip Terminal, right-click the app, choose Open, and confirm. Please only do this with builds from the official repo. Notarization is on my to-do list. (The pip install doesn't have this problem.) What I learned 1. Trust is a feature. Showing "Review first: 32.90 GB" instead of a giant green button made the tool feel more useful, not less. 2. Boring consistency matters. One icon file, one version constant. Half of v3.0.5 was just deleting duplication. 3. Local-first is a relief. No servers, no accounts, and nothing leaves your machine. Try it, break it, tell me It's open source under Apache 2.0: - Download: github.com/NK2552003/Mac-Cleaner/releases/tag/v3.… - GitHub: NK2552003/Mac-Cleaner - PyPI: pypi.org If you find an app footprint it misses, or a path it should protect, open an issue. And if it frees up some space for you, a star helps more than you'd think. So, what's the most surprising thing taking up space on your Mac? Happing Coding ;) !Image description