Mac Storage Genie

Mac Storage Genie is an open-source, local-first macOS storage command center for people who are tired of guessing what is safe to delete, what is actually consuming disk, and where the space went.

The goal is simple: make storage cleanup on macOS fast, understandable, and safe enough that both casual users and power users can trust it.

Screenshots

Empty State

The first-run overview is designed to feel approachable instead of overwhelming: quick scan actions are front and center, safety is called out early, and the app explains the value it provides before asking for a deep scan.

Active Scan

During a scan, the dashboard streams partial results, shows live scan progress, and keeps core metrics like indexed size, reclaimable space, watched locations, and category breakdowns visible while the crawl is still running.

Why This Exists

macOS can tell you that storage is full, but it often does not make the next step obvious:

• what actually grew
• which folders are safe to clean
• what is reclaimable versus dangerous
• where developer tooling, caches, logs, and app data are hiding
• how to search and explore storage faster than Finder

Mac Storage Genie is built to answer those questions with a native macOS app, a persistent SQLite index, deterministic safety heuristics, and a cleanup workflow that defaults to Trash-first behavior.

Current Status

This project is actively under development and already includes a substantial working foundation:

• native SwiftUI macOS app shell
• quick scan and full scan modes
• persistent SQLite-backed index
• indexed search and saved searches
• Explorer with paged loading for large folders
• overview dashboard with trends, watch list, and cleanup guidance
• rule-based cleanup suggestions and dry-run cleanup
• scan issue logging and export
• folder growth review insights and monitoring
• scheduled scans while the app is open
• benchmark harness and test suite

The app is useful today, but it is not “done.” Performance, polish, and platform integration are still improving.

Principles

• Fast: scan quickly, stream partial results, and optimize repeat scans aggressively.
• Safe: clearly separate safe cleanup from caution zones and protected paths.
• Actionable: show what to do next, not just raw file trees.
• Trustworthy: explain what folders are and why they matter.
• Local-first: no cloud dependency and no telemetry by default.

What Works Today

Scanning and Indexing

• quick scan and full scan entry points
• pause, resume, and cancel controls
• explicit permission-denied and skipped-path tracking
• hidden-file and symlink settings
• low-space preflight protection before scans
• SQLite WAL checkpointing and compaction controls
• partial-result preservation on cancellation

Overview

• total indexed size
• reclaimable space estimate
• free disk space
• top categories
• largest folders and files
• growth since last scan
• 24-hour, 7-day, and 30-day trend summaries
• watched locations dashboard
• current and latest scan issue log export

Explorer

• root navigation
• breadcrumb navigation
• double-click folder traversal
• manual refresh
• paged loading for large directories
• Finder reveal and path copy

Search

• indexed search by name
• partial-path search
• extension filters
• size filters
• modified-date filters
• category, risk, and file-kind filters
• saved searches
• CSV export

Cleanup and Intelligence

• cleanup candidates with safety levels
• dry-run cleanup
• Trash-first cleanup
• optional permanent delete
• cleanup journal and restore support
• folder explanations
• risk labels and reclaim planning
• developer-focused cleanup surfaces

Monitoring

• low disk alerts
• rapid growth alerts
• folder growth review alerts
• weekly summaries while the app is open
• scheduled daily scans while the app is open

Architecture

The package is intentionally modular:

• StorageDomain: shared models, enums, formatting, and app-facing domain types
• ScanEngine: filesystem traversal, progress reporting, pause/resume/cancel, and scan event streaming
• IndexStore: SQLite storage, FTS search index, aggregates, snapshots, and export helpers
• IntelligenceEngine: category classification, risk labeling, explanations, cleanup candidates, and recommendation logic
• CleanupEngine: dry runs, Trash-first cleanup, restore flow, and cleanup history
• AppShell: SwiftUI macOS app, settings, overview, explorer, search, monitoring, and scheduling
• Benchmarks: synthetic file tree generation and benchmark runner

Requirements

• macOS 15 or newer
• Swift 6.2+
• Xcode 16+ recommended

Getting Started

Build

swift build

Test

swift test

Open In Xcode

open Package.swift

Select the MacStorageGenieApp executable scheme and run from Xcode.

Run From Terminal

swift run MacStorageGenieApp

Full Disk Access

The app works without Full Disk Access, but major protected storage sources can stay partially invisible.

If you want deeper visibility into Library data, app containers, caches, logs, Messages, and similar locations:

• running from Xcode: give Xcode Full Disk Access
• running from Terminal: give Terminal Full Disk Access

Benchmark Harness

Generate a synthetic file tree:

./.build/debug/GenieBenchmarks generate /tmp/mac-storage-genie-fixture

Run the scan/search benchmark:

./.build/debug/GenieBenchmarks run /tmp/mac-storage-genie-fixture

Local Data and Privacy

Mac Storage Genie is local-first.

• scan index and SQLite data live under ~/Library/Application Support/MacStorageGenie/
• settings live in ~/Library/Preferences/
• there is no telemetry by default
• there is no cloud AI dependency in the current implementation

If system notifications are enabled, they are only used for the app’s own alerts.

Reclaimable Space

The app’s reclaimable-space value is a heuristic estimate based on deterministic cleanup intelligence. It is not the same as macOS “purgeable” storage.

In practice, reclaimable space means:

• items the app believes are candidates for safe or reviewable cleanup
• files and directories that are not treated as protected system-critical data
• recommendation-backed cleanup opportunities rather than speculative total bytes

Open Source Roadmap

The current codebase intentionally defers some major areas until the core experience is stronger:

• exact duplicate detection
• public plugin/module API
• always-on background agent when the app is closed
• menu bar extra return
• richer package-content controls
• Mac App Store sandboxed variant

Contributing

Contributions are welcome.

Useful ways to contribute:

• performance profiling and scan-speed improvements
• classification and cleanup rules for known storage hogs
• better permission-aware UX
• explorer and visualization polish
• benchmark fixtures and regression tests
• docs, bug reports, and reproducible issue cases

When contributing:

• keep safety and explainability high priority
• prefer measurable performance changes over guesswork
• avoid destructive behavior by default
• add tests for storage math, cleanup rules, or scan behavior when practical

Development Notes

• the repo uses Swift Package Manager with multiple local targets
• SQLite is the source of truth for indexed data
• the benchmark harness is useful when evaluating scan/index/search changes
• large real-world scans can put pressure on disk space because the app builds a real local index

License

This project is licensed under the MIT License. See LICENSE.