Overview

Mac Retriever is a full-featured Gmail client and file management system for macOS that unifies multiple Gmail accounts into a single interface with blazing-fast search, smart categorization, and complete email management — plus lightning-fast file indexing (100GB in ~90 seconds) and intelligent cloud storage optimization with custom rules.

The problem: Your digital life is scattered across multiple Gmail accounts, old Outlook PST archives, and 100GB+ of local files. Finding that one email from three years ago, or a PDF buried in your Documents folder, means logging into multiple accounts, using slow Spotlight searches, and manually managing what stays local vs. what goes to cloud storage.

The solution: Mac Retriever is a complete Gmail client and file management system that imports everything — Gmail via OAuth API, PST/MBOX archives, and local files — into a single local SQLite database with FTS5 full-text search. It indexes 100GB of files in ~90 seconds, performs full-text search across everything (emails, attachments, local files) in ~8 minutes, and provides intelligent cloud storage management with custom rules to automatically push local files to cloud-only storage while maintaining full metadata and searchability.

Your data stays on your Mac. Fully offline-capable after import.

Performance

Blazing-fast indexing and search:

• 100GB indexed in ~90 seconds - SQLite + FTS5 optimized for speed
• Full-text search in ~8 minutes - Search across emails, attachments, and local files
• Instant metadata search - Cloud-only files remain searchable without local download
• Custom cloud rules - Automatically push local files to cloud-only storage based on your criteria

Key Features

• Full Gmail Client - Compose, reply, forward, and delete emails from any connected Gmail account
• Multi-account OAuth Sync - Connect multiple Gmail accounts via OAuth, continuous resync with bidirectional changes
• Lightning-Fast File Indexing - Index 100GB of local files in ~90 seconds, FTS across everything in ~8 minutes
• Cloud Storage Optimization - Custom rules to push local files to cloud-only storage while maintaining full metadata
• Cloud-Only File Metadata - Full searchability of cloud-only files without downloading them locally
• PST/MBOX Archive Import - Bring in legacy Outlook archives alongside Gmail
• Full-text Search (FTS5) - Instant search across all email content, attachments, and local files
• Smart Email Categorization - Automatic classification into VIP, Review, Metadata, Junk
• Unified Inbox - Search and manage all accounts simultaneously from one interface
• Duplicate Detection - Find and manage duplicate files across your collection
• Dark Theme UI - Clean PyQt6 interface with Silver Wizard design system
• Production-grade Infrastructure - Crash recovery, auto-updates, one-click bug reporting

Installation

# Clone repository
git clone https://github.com/SilverWizardAI/MacR.git
cd MacR

# Run with UV package manager
uv run python3 ui_pyqt6/run_pyqt.py

Quick Start

1. Connect Gmail Account:

   • Click “Add Account” in Mac Retriever
   • Authenticate via Google OAuth
   • Choose import method (API or Takeout)

2. Import Email:

   • Full import via Gmail API (slower, incremental)
   • Or bulk import from Google Takeout (faster, one-time)

3. Search Everything:

   • One search box for all accounts
   • Full-text search with instant results
   • Filter by account, category, date range

4. Manage and Send:

   • Compose new emails
   • Reply to threads
   • Forward with attachments
   • Delete unwanted emails
   • Changes sync back to Gmail via OAuth

Use Cases

Primary Gmail Client

Replace web Gmail with a native macOS app. Manage multiple Gmail accounts from one unified inbox. Full email management — compose, reply, forward, delete — with OAuth sync. Search everything including attachment contents.

Cloud Storage Optimization

100GB+ local storage eating your SSD? Set custom rules to push files to cloud-only storage (Dropbox, iCloud, etc.) while maintaining full metadata and searchability. Search cloud-only files without downloading them.

Lightning-Fast File Search

100GB indexed in 90 seconds. Full-text search across emails, attachments, and local files in 8 minutes. Find that PDF, doc, or spreadsheet instantly — no more waiting for Spotlight.

PST Archive Preservation

Migrating from Outlook/Exchange? Import PST archives and search alongside Gmail. No data left behind.

Privacy-First Email Management

Your entire email archive lives locally in SQLite. No cloud dependency after import. Full offline access.

Family Shared Mac

Multiple users on one Mac can each have their own accounts imported and categorized separately.

Digital Life Archaeology

“I know I have that email from 2018 somewhere…” — with Mac Retriever, you actually can find it. Emails, attachments, local files — all searchable in one place.

Architecture

┌─────────────────────────┐
│   Mac Retriever UI      │
│   (PyQt6)               │
└──────────┬──────────────┘
           │
    ┌──────▼──────────────────┐
    │  SQLite + FTS5          │
    │  (local database)       │
    └──────┬──────────────────┘
           │
    ┌──────▼──────────────────┐
    │  Import Pipeline        │
    │  • Gmail API            │
    │  • PST Parser           │
    │  • MBOX Parser          │
    │  • Google Takeout       │
    └─────────────────────────┘

All data is stored locally in SQLite with FTS5 full-text search indexes. The Gmail API via OAuth handles import, sending, and bidirectional sync — compose/reply/forward/delete operations sync back to Gmail automatically.

What Makes It Different

vs. Web-based Gmail:

• Local-first — entire archive lives on your Mac, instant offline access
• Multi-account unified inbox — all Gmail accounts in one interface
• FTS5 search includes attachments — find text inside PDFs, docs, spreadsheets
• PST archive support — bring legacy Outlook data forward
• File management — emails + local files in one searchable database

vs. Spotlight Search:

• Blazing fast — 100GB indexed in 90 seconds vs. hours with Spotlight
• Full Gmail client — not just search, complete email management
• Smart categorization — automatic VIP/Review/Metadata/Junk classification
• Cloud optimization — custom rules for cloud-only storage with full metadata
• OAuth sync — compose/reply/forward/delete syncs back to Gmail

vs. Paid Tools (Mailmate, etc.):

• Free and open source — MIT licensed
• Handles PST archives — not just IMAP/Gmail
• File indexing included — search local files alongside emails
• Built with modern stack — Python 3.13, PyQt6, SQLite FTS5

Perfect For

• Anyone who wants a native macOS Gmail client with multi-account support
• People with 100GB+ local files who need lightning-fast search (90-second indexing)
• Users optimizing cloud storage with custom rules for cloud-only files
• People with multiple Gmail accounts who need unified search and management
• Anyone migrating from Outlook/Exchange with PST archives to preserve
• Privacy-conscious users who want local-first email with offline access
• Families sharing a Mac who need separate account views
• Anyone searching for text inside email attachments and local files (PDFs, docs, spreadsheets)

Best Practices

1. Import via Google Takeout first - Faster for initial bulk import, then use API for incremental updates
2. Use smart categories - Let Mac Retriever auto-categorize, then train it on your patterns
3. Regular backups - Database is in ~/Library/Application Support/MacRetriever/ — include in Time Machine
4. Archive old accounts - Import once, then disconnect OAuth for accounts you no longer actively use

Development Status

Current Status: Alpha

What works:

• ✅ Multi-account Gmail import (API + Takeout)
• ✅ PST/MBOX archive import
• ✅ Full-text search with FTS5
• ✅ Smart email categorization
• ✅ Compose, reply, forward
• ✅ Duplicate detection
• ✅ Production infrastructure (crash recovery, auto-updates, bug reporting)

In progress:

• 🚧 Family alpha testing
• 🚧 Advanced search filters
• 🚧 Attachment management improvements

Roadmap:

• 📋 Public beta
• 📋 Attachment content indexing (PDFs, docs)
• 📋 Plugin system for custom categorizers

Tech Stack

• Python 3.13 - Core application
• PyQt6 - Cross-platform UI framework
• SQLite + FTS5 - Database with full-text search
• Google Gmail API - Email import and sending
• Google OAuth 2.0 - Secure authentication
• UV Package Manager - Fast Python dependency management
• sw2_logging - Telco-grade logging infrastructure
• CrashGuard - Automatic crash recovery
• AutoUpdater - One-click app updates

Documentation

• Getting Started Guide
• Import Strategies
• Search Tips
• Privacy & Security

Support

• GitHub Issues (repo is currently private)
• GitHub Discussions
• Email: support@silverwizard.dev

---

Note: Mac Retriever is currently in alpha and the repository is private. Public release planned after family alpha testing is complete.