haseab / retrace

Retrace > ⚠️ **VERY EARLY DEVELOPMENT** - This project is in very early development. Expect breaking changes, incomplete features, and bugs. A local-first screen recording and search application for macOS, inspired by Rewind AI. Retrace captures your screen activity, extracts text via OCR, and makes everything searchable—all locally on-device. What is Retrace? Retrace is an open source alternative to Rewind AI that gives you photographic memory of everything you've seen on your screen. It continuously captures screenshots (every 2 seconds by default), extracts text using OCR, and stores everything in a searchable database—entirely on your Mac with no cloud dependencies. Current Status ✅ What's Working • **Continuous screen capture** with configurable intervals (every 2 seconds default) • **OCR text extraction** using Apple's Vision framework • **Full-text search** with advanced filters (app, date, exclusions) • **Timeline viewer** - Scrub through your screen history frame-by-frame • **Dashboard analytics** - Visualize app usage, screen time, and activity patterns • **Rewind AI import** - Seamless, resumable background import of existing Rewind data • **Settings panel** - Comprehensive controls for capture, storage, privacy, and shortcuts • **Global hotkeys** - Quick access (Cmd+Shift+T for timeline, Cmd+Shift+D for dashboard) • **HEVC video encoding** - Working but not yet optimized for efficiency • **Search highlighting** - Visual highlighting of search results in frames • **Privacy controls** - Exclude apps and private browsing windows 🚧 Coming Soon • **Optimized storage** - Improving HEVC compression efficiency • **Audio recording and transcription** - Whisper.cpp integration ready but disabled • **Advanced keyboard shortcuts** - More customizable shortcuts • **Decrypt and backup Rewind database** - Export your Rewind data Architecture **Data Flow:** Retrace is built with a modular architecture: • **Database** - SQLite + FTS5 for metadata and full-text search • **Storage** - HEVC video encoding for screen recordings • **Capture** - Screen capture using CGWindowListCapture API • **Processing** - OCR text extraction using Apple's Vision framework • **Search** - Query parsing, FTS5 ranking, and result snippets • **Migration** - Import from Rewind AI databases • **App** - Coordination, lifecycle management, service container • **UI** - SwiftUI interface with search, timeline, and settings See AGENTS.md for detailed architecture documentation. Tech Stack Active • **Language**: Swift 5.9+ with async/await, Actors, Sendable • **Platform**: macOS 13.0+ (Apple Silicon required) • **UI**: SwiftUI with custom design system • **Screen Capture**: CGWindowListCapture API (legacy, no privacy indicator) • **OCR**: Vision framework (macOS native) • **Video**: VideoToolbox (HEVC encoding) • **Database**: SQLite with FTS5 full-text search • **Encryption**: CryptoKit (AES-256-GCM) for database Planned for Future Releases • **Audio transcription**: whisper.cpp (bundled, ready but disabled) • **Embeddings**: llama.cpp for semantic search (prepared but not active) Requirements • **macOS 13.0+** (Ventura or later) • **Apple Silicon** (M1/M2/M3) - Intel not supported • **Xcode 15.0+** or Swift 5.9+ for building from source Permissions Required Retrace needs the following macOS permissions: • **Screen Recording** - To capture your screen • **Accessibility** - For enhanced context extraction (app names, window titles, browser URLs) Quick Start • Clone the Repository • Build and Run **Option A: Using Xcode (Recommended)** • Wait for Swift Package Manager to resolve dependencies • Select the scheme in Xcode • Build and run (⌘R) **Option B: Command Line** **First Launch:** • Grant **Screen Recording** permission when prompted (System Settings → Privacy & Security) • Grant **Accessibility** permission for enhanced context extraction • Complete the onboarding flow • Optionally import existing Rewind AI data • Configure settings (capture interval, excluded apps, shortcuts) The app will create its database at the default location ( ) or a custom location if configured in Settings. • Development Scripts **Reset database** (keeps settings): **Reset onboarding** (safe, preserves data): **Hard reset** (deletes everything): **Draft or submit a bug issue**: Development Retrace follows a Test-Driven Development (TDD) approach. See CONTRIBUTING.md for: • Development workflow and conventions • Testing requirements (TDD, mocking protocols) • AI-assisted development guidelines • AI bug issue template • Module boundaries and architecture decisions • Code style and Swift patterns Running Tests Project Structure Roadmap Current Release ✅ • [x] Screen capture with deduplication • [x] OCR text extraction (Vision framework) • [x] Full-text search (SQLite FTS5) • [x] Dashboard with app usage analytics • [x] Timeline frame viewer • [x] HEVC video encoding (working but not optimized) • [x] Settings and preferences • [x] Rewind AI import (resumable) • [x] Menu bar and global hotkeys • [x] Search highlighting Future Releases - TBD _Roadmap for future releases to be determined based on user feedback and priorities._ Performance **Current Metrics:** • **Capture Rate**: Every 2 seconds (configurable: 1-60 seconds) • **OCR Speed**: ~200-500ms per frame on Apple Silicon • **Search Speed**: <100ms for typical queries **Storage (Work in Progress):** • **Current**: ~50-70GB/month (HEVC working but not optimized) • **Target**: ~15-20GB/month with optimized compression Known Limitations • **macOS 13.0+ and Apple Silicon only** - Intel Macs not supported • **Storage not yet efficient** - Currently 4-5x less efficient than Rewind AI (~50-70GB/month vs ~15GB/month). HEVC encoding is working but not optimized • **No audio capture** - Audio recording and transcription infrastructure exists but is currently disabled See GitHub Issues for known bugs and feature requests. Privacy & Security • **100% Local** - All pro…