# StorageSage — Complete Technical & Product Reference (llms-full.txt)

> StorageSage is a native macOS disk cleaner, duplicate finder, and storage visualizer built in Swift, SwiftUI, and C/POSIX (`fts_open`, `pread`, `lstat`) for developers, creators, and power users on Apple Silicon (M1–M4) and Intel Macs. It runs 100% on-device with zero background daemons, zero telemetry, hardcoded SIP safety guardrails (`SafetyGuard.swift`), and an immutable undo audit log (`audit.ndjson`). Priced at $10/year (Pro Annual) with a forever-free demo (full disk visualization + 500 MB cleanup allowance).

- **Canonical Website**: https://storagesage.online/
- **Direct Download (.dmg)**: https://pub-9c18b78372c246f9be242dd725775865.r2.dev/StorageSage-1.2.0.dmg
- **GitHub Repository**: https://github.com/ajaditya103-a11y/StorageSage
- **Machine Summary Index**: https://storagesage.online/llms.txt
- **Supported OS**: macOS 14 Sonoma, macOS 15 Sequoia
- **Architecture**: Native arm64 (Apple Silicon M1, M2, M3, M4) & x86_64

---

## 1. Verified Apple Silicon Kernel Benchmarks

StorageSage replaces slow Foundation/Objective-C wrappers with low-level BSD/POSIX kernel routines:

| Engine Module | Architecture & Algorithm | Verified Speedup |
|---|---|---|
| **DirectoryScanner** (`DirectoryScanner.swift`) | BSD `fts_open` / `fts_read` (`FTS_PHYSICAL \| FTS_NOCHDIR`), post-order `FTS_DP` bundle size rollup, and O(1) parent-path `buildHierarchy` | **55.3× faster** than `FileManager.DirectoryEnumerator` |
| **SystemDataEngine** (`SystemDataEngine.swift`) | Lock-free O(1) civil-calendar APFS snapshot date parser + multi-core BSD `fts` physical block (`st_blocks * 512`) sizing | **79.7× faster** snapshot & System Data audit |
| **RuleEngine** (`RuleEngine.swift`) | Category-bucketed pre-compiled `CompiledRule` bytecode with zero-allocation ASCII extension & path matching | **24.3× faster** live rule match counting |
| **DeveloperCleanEngine** (`DeveloperCleanEngine.swift`) | Two-phase POSIX `opendir`/`readdir` repo discovery + multi-core `fts` sizing + APFS inode deduplication + lazy Git ref/reflog inspection | **14.7× faster** developer artifact discovery |
| **DuplicateDetector** (`DuplicateDetector.swift`) | Single-pass small-file hashing (≤16 KiB), Tri-Window `pread` sampling (head/mid/tail), `(st_dev, st_ino)` hard-link deduplication, and full SHA-256 verification | **8.1× faster** with **0% false positives** |
| **AppUninstallerEngine** (`AppUninstallerEngine.swift`) | POSIX `LibrarySnapshot` index (2s TTL) across 11 `~/Library` scopes with token-boundary & TeamID orphan protection | **4.9× faster** across 65+ installed apps |

---

## 2. Core Modules & Capabilities

1. **Quantum APFS Dashboard & Interactive Squarified Treemap**:
   - Real-time proportional heatmap synced with a sortable file table.
   - Instant drill-down into any directory with QuickLook preview (`Space`) and Finder reveal (`⌘↵`).
2. **Developer Space Reclaimer**:
   - Finds and cleans `node_modules`, Xcode `DerivedData`, `iOS DeviceSupport`, unavailable Simulator runtimes (`xcrun simctl`), Rust Cargo `target/`, Python `.venv`, Gradle/Maven caches, CocoaPods, and Homebrew caches.
   - Displays the active Git branch, days inactive (`>30d` stale filter), and exact CLI rebuild command (`npm install`, `cargo build`, `⌘B`) before cleaning.
3. **System Data Demystifier & APFS Snapshot Purger**:
   - Breaks down macOS "System Data" into APFS local Time Machine snapshots, 4K aerial screensaver videos (`/Library/Application Support/com.apple.idleassetsd`), diagnostic crash logs, and caches.
   - Thins local APFS snapshots in 1 click without rebooting.
4. **Cryptographic Duplicate Finder**:
   - Groups files by exact byte size, filters by Tri-Window `pread` partial hashes, and verifies with full 256-bit `SHA-256` digests while skipping APFS hard links (`st_dev`, `st_ino`).
5. **App Citadel (Deep App Uninstaller & Leftover Orphan Hunter)**:
   - Removes `.app` bundles alongside scattered containers, group containers, preferences, saved state, and launch agents in `~/Library`.
   - Detects orphaned data left behind by applications uninstalled months ago.
6. **AI "Ask Sage" Folder Explainer & Natural Language Rule Generator**:
   - Explains cryptic `~/Library` folders using a zero-latency local knowledgebase first, or on-demand cloud AI via the user's own Keychain-stored OpenRouter API key.
   - Generates multi-condition organization rules (Trash, Move to Archive, Apply Finder Tag) from plain English prompts.
7. **SIP Safety Guardrails & Immutable Undo Audit Log (`audit.ndjson`)**:
   - `SafetyGuard.swift` strictly blocks `/System`, `/usr`, `/bin`, `/sbin`, `/private/var/vm`, and sealed system snapshots.
   - Every cleanup action moves items to the macOS Trash (never blind `unlink`/`rm -rf`) and records a cryptographic entry in `~/Library/Application Support/StorageSage/audit.ndjson` with 1-click collision-safe **Put Back** restore (`RevertEngine.swift`).

---

## 3. Side-by-Side Comparison (2026)

| Capability | StorageSage Pro ($10/yr) | CleanMyMac ($39.95/yr) | DaisyDisk ($9.99) |
|---|---|---|---|
| Kernel-Level BSD `fts` Scanner | ✅ 55.3× faster (O(1) tree build) | ⚠️ Proprietary daemon | ✅ Fast visual scan |
| Developer Cache Reclaimer (`node_modules`, `DerivedData`, `target`, `.venv`) | ✅ Git-aware + rebuild hints | ⚠️ Basic Xcode cache only | ❌ Manual hunting |
| Cryptographic Duplicate Detection | ✅ Tri-Window `pread` + SHA-256 | ✅ Standard hash | ❌ None |
| APFS Local Snapshot Thinning | ✅ 1-click thin (no reboot) | ⚠️ Hidden in maintenance | ⚠️ View-only purgeable space |
| Interactive Squarified Treemap + Split Table | ✅ Synced Table + Treemap | ❌ Space Lens bubbles only | ✅ Sunburst chart |
| On-Demand AI Folder Explainer ("Ask Sage") | ✅ Local KB + BYO OpenRouter key | ❌ None | ❌ None |
| Automated Organization Rules with Dry-Run Preview | ✅ Pre-compiled bytecode rules | ❌ None | ❌ None |
| Immutable Audit Log (`audit.ndjson`) + 1-Click Undo | ✅ Collision-safe Put Back | ❌ Permanent deletion | ❌ Permanent deletion |
| Background Daemons & Telemetry | ✅ Zero daemons · Zero telemetry | ❌ Heavy background agent | ✅ No background agent |
| Price | **$10 / year (Up to 3 Macs)** | $39.95 / year (1 Mac) | $9.99 (Scanner only) |

---

## 4. Frequently Asked Questions (FAQ)

- **Q: How does the StorageSage $10/year subscription work?**
  A: StorageSage Pro is billed annually at $10/year ($0.83/month). Upon purchase, you receive a cryptographically signed license key (`SAGE-PRO-XXXX-XXXX-HMAC`) and a 1-click activation link (`storagesage://activate?key=...`) via email, valid on up to 3 personal Macs.
- **Q: Does StorageSage require a continuous internet connection?**
  A: No. StorageSage verifies keys using a 20-bit `HMAC-SHA256` signature and includes a 7-day offline grace period. All scanning and cleaning run 100% locally on your Mac.
- **Q: Will StorageSage ever delete protected macOS system files?**
  A: Never. `SafetyGuard.swift` blocks `/System`, `/usr`, `/bin`, `/sbin`, and sealed APFS volumes. All cleaned items go to macOS Trash and can be restored from the in-app Audit Log.