Catalogue

Catalogue is a local-first macOS capture archive. Hold the trigger key, capture the current screen, then attach either a voice note or typed context and review everything inside a calm native macOS app.

Current Scope

• Native SwiftUI macOS app
• Home, Inbox, Timeline, Search, and Settings
• Local settings persistence
• Global hold-to-capture flow
• Full-display screenshot capture
• Typed-note fallback flow
• Voice recording with local transcription
• Timeline archive browsing with local filtering
• Global full-library text search
• Menu bar presence and background utility behavior
• First calendar event creation flow from entries
• Local JSON metadata store plus Application Support file storage

Project Structure

Catalogue/
  App/
  Models/
  Services/
  Stores/
  Utilities/
  Views/
  Resources/
project.yml
Catalogue.xcodeproj

Requirements

• Xcode 16+
• macOS 14+
• Screen Recording permission
• Microphone permission for voice capture
• Input Monitoring permission for the global trigger key monitor
• Calendar permission for event creation from entries

Build

1. Generate the project when needed:

   xcodegen generate

2. Open Catalogue.xcodeproj in Xcode.

3. Run the Catalogue target.

Permissions And Manual Setup

Catalogue relies on native macOS privacy controls:

• Screen Recording: required for screenshot capture.
• Microphone: required for voice notes.
• Input Monitoring: required so the app can detect the global trigger key while in the background.
• Calendars: required only if you want to create a Calendar event from an entry.

If you deny a permission, the app remains usable and surfaces the missing capability in Settings and Home. You can reopen System Settings from inside the app.

Menu Bar And Background Mode

Catalogue can now behave like a background utility:

• You can keep it in the Dock, the menu bar, or both.
• Closing the last window does not quit the app.
• Capture remains active while the app is resident in the background.
• The menu bar item provides quick access to the app, recent captures, settings, and quit.

Current limitation:

• Dock visibility is switched at runtime using the native activation policy. This works cleanly for the MVP, but it is not a fully separate LSUIElement build target.

Launch At Login

• Launch at login is implemented with ServiceManagement.SMAppService.mainApp.
• It should work on signed builds on macOS 13+.
• In unsigned local debug builds, macOS may still refuse or require approval depending on local system policy.

Calendar Integration

Catalogue's first calendar pass is intentionally conservative:

• Enable calendar integration in Settings.
• Open an entry and use Create Calendar Event or Suggest Event.
• Review the generated draft before confirming.
• Catalogue never auto-creates events.

The app stores a lightweight local link to the created calendar event identifier and title when available.

Persistence

The app stores its local data in the user's Application Support directory:

~/Library/Application Support/Catalogue/

Inside that directory:

• entries.json stores metadata
• Screenshots/ stores PNG captures
• Audio/ stores retained recorded audio files
• Models/ stores local transcription model files used by the app

Architecture Notes

• EntryStore owns metadata persistence and deletion.
• SettingsStore owns user preferences.
• AppNavigationStore owns app-wide section and entry selection.
• EntryRetrieval owns local timeline grouping and search matching.
• AppLifecycleController manages Dock visibility, menu bar utility mode, and launch-at-login synchronization.
• CaptureManager coordinates the global trigger flow.
• OverlayWindowManager renders the fullscreen hold/capture overlay.
• CalendarService owns EventKit permission status and event creation.
• TranscriptionService remains abstracted, even though the app now prefers local whisper.cpp.

Product Shape

• Inbox: recent and operational review surface
• Timeline: chronological archive browsing
• Search: retrieval-first lookup across the full library
• Settings: permissions, capture behavior, theme, and app presence

License

This repository is source-available, not open source.

• You may install and run Catalogue.
• You may not modify it.
• You may not redistribute it.
• You may not share derivative versions.

See LICENSE for the exact terms.

Assumptions

• v1 supports Right Option as the trigger key cleanly, with a future-ready enum for more keys.
• The MVP captures the main display.
• Metadata is stored in JSON for speed of implementation, with a clean seam for SQLite later.
• Menu bar mode and Dock visibility are controlled dynamically at runtime.
• Calendar integration is explicit and opt-in, not automatic scheduling.

TODO

• Expand trigger remapping beyond Right Option.
• Improve event/date extraction beyond the current first-pass detector.
• Add Highlights and Collections as real sections.
• Refine search ranking and result highlighting.
• Add deeper summaries and sync in later versions.