ReaderFlow is a native macOS menu-bar reading aid for understanding difficult English without leaving the text. It provides a progressive English-first help ladder for selectable text from books, documents, editors, and web pages, with Russian translation available only as the final step.
Requirements:
- macOS 15 or newer;
- Xcode Command Line Tools;
- an English dictionary enabled in Dictionary.app;
- Accessibility permission for ReaderFlow;
- Apple's English and Russian translation languages when macOS requests them.
Simpler English prefers Apple Intelligence on macOS 26 and newer. On older or unsupported systems ReaderFlow falls
back to an installed and authenticated Codex CLI using gpt-5.4-mini; no separate OpenAI API key is used.
Build, install, and launch:
./install.shOpen the ReaderFlow menu once, choose Настроить Accessibility…, and enable ReaderFlow under
System Settings → Privacy & Security → Accessibility. A double click or mouse drag selection opens ReaderFlow
automatically; ⌥Space remains the manual trigger. The automatic mode can be disabled from the menu. The app is
installed at ~/Applications/ReaderFlow.app.
./build.sh— compile, ad-hoc sign, and verifybuild/ReaderFlow.app../test.sh— compile and run all deterministic logic tests../install.sh— stop the previous ReaderFlow process, build, install, and launch the new version.
- Select a word and immediately read its English dictionary definition.
- Select a phrase or sentence and receive English definitions for difficult words when available.
- Rewrite difficult prose using Apple's on-device Foundation Model, with Codex GPT-5.4 mini as the compatibility fallback.
- Unlock Russian translation after simpler English, or when Simplify is unsupported on this system.
- Copy the deepest result reached in the help ladder.
- Close the transient popup with Escape, the hotkey, or any click outside it.
ReaderFlow does not use screen capture or OCR. Simplify prefers Apple's on-device Foundation Model. If it is not
available and Codex CLI is installed, ReaderFlow starts an ephemeral, read-only codex exec request using
gpt-5.4-mini. Only the selected passage is sent when the user explicitly presses Simplify. Russian translation
uses Apple's Translation framework only after the user explicitly requests it.
ReaderFlow is format-independent because it operates on the text selected in the frontmost macOS application. It works with selectable text from:
- EPUB readers, including Apple Books and Calibre;
- TXT, Markdown, RTF, and source-code editors;
- web pages and HTML documents;
- word processors and note-taking applications;
- PDFs that contain a real text layer.
Encrypted readers, scanned PDFs, images, and applications that expose neither selected text nor copying are not supported.
- Open an EPUB, TXT file, document, or web page.
- Select a word, phrase, or sentence.
- ReaderFlow opens automatically; alternatively press
⌥Space. - Read the English dictionary help.
- On a supported system, press
2 · Упростить ENonly if the English remains difficult. - Press
3 · Перевести RUif simpler English is insufficient or unsupported on this system. - Press Escape, press
⌥Spaceagain, or click outside the popup to close it.
ReaderFlow first requests the selected text through the macOS Accessibility API. If the host application does not
expose it, ReaderFlow temporarily sends Cmd+C, reads the copied text, and restores the original pasteboard items
and data types.
Open the menu-bar icon and choose Демо: слово из книги or Демо: сложная фраза из книги. Developers can launch
the same flows directly:
build/ReaderFlow.app/Contents/MacOS/ReaderFlow --demo-word
build/ReaderFlow.app/Contents/MacOS/ReaderFlow --demo-phrase- No selection: enable Accessibility permission and retry with selectable text.
- No dictionary result: enable an English dictionary in Dictionary.app.
- Translation is waiting: accept macOS's language-download prompt.
- Simplify is unavailable: install and authenticate Codex CLI, or use macOS 26 with Apple Intelligence and a ReaderFlow build produced by Xcode 26.
⌥Spacedoes nothing: another application may own the shortcut; ReaderFlow reports this in its menu.- Scanned document: add a text layer with OCR in another application before using ReaderFlow.
Sources/AppDelegate.swift— lifecycle, menu commands, permission entry point, and hotkey flow.Sources/SelectionReader.swift— Accessibility selection and lossless clipboard fallback.Sources/DictionaryService.swift— English definitions and difficult-word hints.Sources/AppleSimplificationService.swift— Foundation Models integration and safe compatibility states.Sources/CodexSimplificationService.swift— ephemeral GPT-5.4 mini CLI fallback for older systems.Sources/AutomaticSelectionMonitor.swift— optional double-click and drag-selection activation.Sources/ReaderModel.swift— progressive assistance state and Apple Translation orchestration.Sources/PopupPanelController.swift— transient panel positioning and dismissal.Sources/PopupView.swift— ordered SwiftUI help ladder.Tests/TestRunner.swift— deterministic selection, context, and simplification tests.context.md— original product discussion and design rationale.
selectable text from EPUB, TXT, PDF, HTML, or an editor
│
┌────────────────┴────────────────┐
▼ ▼
Accessibility selection lossless clipboard fallback
└────────────────┬────────────────┘
▼
TextSelection
│
▼
1. English dictionary help
│
▼
2. Apple on-device simplification
or Codex GPT-5.4 mini fallback
│
▼
3. On-demand Apple Russian translation
│
▼
transient SwiftUI popup
The production app is compiled directly with the macOS SDK and packaged by build.sh. A macOS 15 SDK build safely
excludes Foundation Models at compile time. An Xcode 26 SDK build includes the integration while preserving the
macOS 15 deployment target and runtime checks. Development builds use a stable designated code requirement so
rebuilding does not change ReaderFlow's Accessibility identity. Package.swift also supports source-level Swift
Package Manager builds.