Read Assist

An open-source native macOS reading companion for contextual word meanings and plain-language passage explanations. Select text in a book, document, or browser, then ask for help without leaving the reading app.

Read Assist is a small SwiftUI/AppKit menu-bar app: no Electron shell, app server, analytics SDK, or third-party Swift runtime dependencies. It is an early public source release for Apple-silicon Macs running macOS 14 or later. Bring your own OpenAI API key.

Install · Privacy · ReadAssistCore · Discussions · Issues

The supported distribution today is a local source build. From a Mac with Xcode and Swift 6 support:

git clone https://github.com/ai-nuke/read-assist.git
cd read-assist
swift test --disable-sandbox
bash scripts/build-app.sh
bash scripts/install.sh
open "/Applications/Read Assist.app"

In the app:

1. Choose Set up (or the gear), enter your OpenAI API key, and choose Save & Enable.
2. Choose Enable Access and allow Read Assist in System Settings → Privacy & Security → Accessibility.
3. Select a word or passage in your reading app and click the Read Assist button beside the selection, or press Control–Option–R. A word opens its meaning; multiple words open a passage explanation.

The request starts only after the in-app capture action. There is no manual Copy step. If selection capture is unavailable, use the menu-bar Read Copied Text fallback or paste/type into the popup. Both fallback text and the two macOS Services actions stay in a local preview until you click Explain.

• A compact reader opens beside the lookup instead of covering the center of the screen. Longer answers scroll, and the window remains resizable.
• Explain more asks for a fuller answer and makes a separate billable request. Stop preserves partial output and marks it incomplete.
• Escape, Done, or closing the popup cancels the current request and clears the current text and answer. Completed answers can be selected and copied.
• Read Assist does not start at login. The selection button appears after a relevant gesture and hides on another click, scrolling, or app switch. Toggle Show Button on Text Selection from the menu-bar icon.

• Nothing is sent to OpenAI until you explicitly request an explanation. Only the selected word or passage is sent; Read Assist does not read a whole book or collect surrounding document content outside that selection.
• The API key is stored in the user's macOS Keychain. There is no reading history, screenshot capture, analytics, response cache, or continuous clipboard monitor.
• Requests use store: false, but that is not a promise of zero provider retention. OpenAI's current API data policies still apply.
• You use your own OpenAI API key and are responsible for provider billing. Cancellation cannot undo tokens already processed by the provider.

Read the full privacy model before enabling live requests.

• The app currently targets Apple silicon (arm64) and macOS 14+.
• Accessibility permission is required for the selection button. Reader and document support varies by app and macOS version; Books and browser/PDF behavior need acceptance testing on the specific setup.
• Protected fields, inaccessible views, and image-only scans may not expose selectable text. Image-only scans need OCR outside this version.
• Automated tests use simulated transport and never call a live API. Live answer quality, billing, latency, Keychain behavior, Accessibility, and reader compatibility are manual acceptance areas.
• scripts/build-app.sh creates a versioned developer archive and checksum, but the archive is ad-hoc signed and not notarized. Gatekeeper may reject it on another Mac. Build from source until a Developer ID-signed and notarized release is available.

See testing and known limitations for the current evidence and support for privacy-safe bug reports.

Trying it? A short report with your macOS version, Mac architecture, reader app, and whether the fallback worked is more useful than a generic success report. Open an issue without including reading text, keys, or private screenshots.

ReadAssistCore is a Foundation-only library product for reader integrations. It provides bounded input validation, exact selected-word context, an ExplanationClient protocol, OpenAI Responses transport, and streaming parsing. It does not access Accessibility, the clipboard, Keychain, SwiftUI, or AppKit, so an integration can supply its own UI, consent flow, and secure credential storage.

Start with the ReadAssistCore integration guide, then review the architecture and public API in Sources/ReadAssistCore.

The package requires a macOS 14+ host and an Xcode/Swift 6 toolchain. No API key is needed for tests or a release build:

swift test --disable-sandbox
swift build -c release
bash scripts/build-app.sh

The build script validates the property list and ad-hoc signature, then writes dist/ReadAssist-<version>-arm64.zip and its SHA-256 checksum. The installer extracts the matching archive to /Applications/Read Assist.app; quit the app from its menu-bar icon before reinstalling. The CI workflow is configured to run the same package/checksum checks on macos-14.

Useful contribution paths include reader compatibility reports, privacy-safe fixtures and tests, ReadAssistCore integrations, and Developer ID/notarized distribution. Read CONTRIBUTING.md, the public roadmap, and the 21-day launch guide.

If the selection button fails, use Save Selection Diagnostics in the menu-bar menu and attach only that JSON. It contains permission/monitor flags, counters, version, export time, and fixed outcome labels—not selected text, clipboard data, key values, document titles, or app names.

The application source and documentation are licensed under the Apache License 2.0. Read Assist names, logos, icons, screenshots, and other brand assets are not granted under that license; see NOTICE.