Freddie is a macOS paper reader built with SwiftUI. The app bundle name is Freddie, while the project name remain ReadPaper.
It focuses on three practical reading workflows:
- import local PDFs with conservative metadata extraction
- import arXiv papers by ID or URL and prefer HTML reading when available
- translate papers through semantic HTML blocks or full-PDF BabelDOC output
- Local-first paper library backed by SwiftData
- Local PDF import with lightweight metadata detection from PDF info and early pages
- arXiv import with step-by-step progress feedback
- arXiv HTML fallback chain:
arxiv.org/html/{id}first, thenar5iv - Readability-based HTML extraction and localization for a cleaner reading view
- Reversible region editing for imported HTML: hide leftover navigation, share bars, or other clutter one block at a time or a whole run with Shift-click, and restore it any time
- Incremental HTML translation with per-block persistence and refresh
- Multi-provider, multi-model OpenAI-compatible routing
- Full PDF translation via BabelDOC with structured progress reporting
- PDF, HTML, and dual-PDF reading modes in one app
Mac, iPad and the cross-platform Freddie for Windows, Linux and macOS can sync the same paper library through a self-hosted Freddie Sync Server. Freddie ships without a default server: whoever deploys the server issues a credential file for each device, and you import it in Settings → Sync. Freddie shows the server address and asks before uploading anything. See the sync guide for setup, conflict handling, and what is synced.
- macOS 14.0+
- Xcode with Swift 6 support
xcodegen
Xcode resolves the Swift packages from their GitHub repositories. The selected
branches are declared in project.yml; no sibling repository checkouts are
required. The scripts/build command also downloads or builds the
manifest-verified BabelDOC native runtime assets in Xcode's package checkout.
Core ML conversion checks its pinned inputs and output structure, then records
the generated model's SHA-256 in the bundled runtime manifest. The conversion
output does not need to match a precomputed artifact hash.
create-dmg is only needed if you want to build a distributable DMG locally.
Clone the repository:
git clone <your-repo-url>
cd read-paperGenerate the Xcode project:
xcodegen generateOpen the project:
open ReadPaper.xcodeprojOr build from the command line:
./scripts/buildThe build script performs an unsigned Release build, verifies the embedded
BabelDOC runtime and helper, and writes the app to
build/Release/Freddie.app; compilation intermediates remain under
/tmp/read-paper-derived-data, so the repository and release directory stay
free of compilation intermediates. Run
./scripts/build --help for Debug builds, custom output paths, optional
XcodeGen project regeneration, and Xcode signing options.
Run tests:
xcodebuild -project ReadPaper.xcodeproj -scheme ReadPaper -destination 'platform=macOS' -derivedDataPath /tmp/read-paper-derived-data testEnable the repository's Git hooks once per clone:
git config core.hooksPath .githooksThe pre-commit hook increments the marketing version and build number together,
then stages only those version fields in project.yml and the generated Xcode
project. The patch component runs from 0 through 20, and the minor component
runs from 0 through 9: 0.3.19 becomes 0.3.20, 0.3.20 becomes 0.4.0,
and 0.9.20 becomes 1.0.0. To set an explicit version, change
MARKETING_VERSION and CURRENT_PROJECT_VERSION together in project.yml;
the hook preserves and stages that change even if project.yml was not staged
yet.
ReadPaper/Models: SwiftData models and enumsReadPaper/Views: app UI, library, inspector, settingsReadPaper/Readers: PDF, HTML, and dual-PDF readersReadPaper/Services: import, arXiv, HTML localization, translation, BabelDOC, storageReadPaperTests: unit tests for import, storage, translation, routing, and subprocess behaviorproject.yml: XcodeGen project definition
ReadPaper does not treat arbitrary PDF text extraction as a reliable full-document structure source.
- Local PDFs are used for reading and lightweight metadata identification
- arXiv papers prefer HTML as the structured reading and translation carrier
- full PDF translation is delegated to BabelDOC
Primary application data is stored under:
~/Library/Application Support/ReadPaper/
Key locations there:
ReadPaper.store: the SwiftData store for papers, attachments, translation cache, provider/model profiles, and app settingsLibrary/{paper UUID}/: per-paper files such aspaper.pdf,paper.html,Resources/,translations/, andnotes/Tools/: legacy or optional app-managed external tool files
The native BabelDOC helper and its manifest-pinned MuPDF, zstd, layout model, and font runtime are bundled with the app; no separate runtime install step is required.
Even though the app bundle name is Freddie, the on-disk application support directory currently remains ReadPaper.
Copyright (c) 2026 SYYANI.
This project is licensed under the GNU Affero General Public License v3.0
(AGPL-3.0-only). See LICENSE for the full license text.
Special thanks to the projects and ideas that helped shape ReadPaper: