Overview
Shelf watches the frontmost macOS application, extracts a useful hint and tries to match it to a person or organisation in Contacts. It then offers actions for that app, contact and selected item.
The project is being migrated from its original Python/PyObjC implementation to a native Swift app for macOS 26. The earlier code remains under legacy/ for reference.
How it works
A monitor follows application activation and polls every two seconds. App-specific extractors read the active browser tab, selected Mail message, Finder selection or selected Contacts record. Other apps fall back to the focused window title through Accessibility.
Contacts resolves URLs, e-mail addresses, names and contact identifiers. Safari context adds Reading List state, previous visits and related pages ranked from local history. For Mail, Spotlight and Latent Semantic Mapping rank similar messages and learn likely destination mailboxes. The resulting context determines which automation actions Shelf can offer.
Features
Native Swift app
Built with Swift 6.2 and SwiftUI for macOS 26. The release script creates a signed or ad-hoc-signed Shelf.app bundle.
Application context
Reads active tabs from Safari, Chrome, Edge and Brave; selected messages from Mail; Finder selections; Contacts selections; and focused window titles.
Contact matching
Uses Contacts to resolve e-mail addresses, URLs, names and selected records without maintaining a separate address book.
Safari context
Combines the active tab with local Safari Reading List and history data to show previous visits and related pages. History access is local and may require Full Disk Access.
Mail assistance
Ranks similar messages with Spotlight, learns mailbox choices with Latent Semantic Mapping and suggests where the selected message should move.
Optional Apple Intelligence
Can produce a short summary of similar Mail results and their filing pattern. The rest of Shelf works without model output.
Contextual automation
Opens Contacts records, composes Mail, starts Messages, opens contact URLs, moves selected Mail, reveals Finder items, copies contact summaries and returns focus to the source app.
Permission controls
Contacts, Accessibility, Automation and Full Disk Access are requested only for the features that need them.
Preserved legacy app
The original Python/PyObjC implementation and py2app build remain available under legacy/.
Architecture
Posts
2026-07-10
The Return of Shelf