PaperMaster

A native macOS workspace for collecting papers, planning what to read next, reading PDFs in-app, and bringing local agents directly into the research loop.

PaperMaster is a paper-reading app for people who do serious literature work and do not want their workflow split across a PDF viewer, a backlog manager, a browser full of arXiv tabs, and a separate AI chat window.

It combines library management, queue planning, in-app reading, AI-assisted synthesis, and an embedded terminal for local agents in one native macOS app. The goal is simple: keep the whole paper workflow in one place, and make it programmable when you need more than a passive archive.

Why PaperMaster

• Read papers where you manage them. Today, Inbox, Queue, Library, Hot Papers, Fusion Reactor, and Reader live in the same workspace.
• Keep your queue realistic. PaperMaster schedules work around a configurable papers/day target and supports reordering, snoozing, and status changes.
• Turn reading into reusable knowledge. Highlights, margin notes, Ask AI, Paper Cards, and Fusion Reactor all sit on top of the same local paper library.
• Bring agents into the app instead of context-switching out of it. The built-in terminal can run local tools like codex directly inside your reading workflow.

Product Tour

Import and organize Import from arXiv URLs, direct PDF links, or local PDFs, then work from a searchable library with metadata, BibTeX, notes, tags, and storage status in one place.	Plan the queue Use Today and Queue to decide what deserves attention now, then keep a polished Paper Card beside the schedule for fast recall later.
Read inside the app Review PDFs with thumbnails, search, page navigation, highlights, notes, selected-text Ask AI, and the in-context Paper Elf critique companion.	Stay ahead of the feed Refresh recent arXiv submissions by category, rank them against your library signals, and import promising papers without leaving the app.
Synthesize ideas Load 2 to 6 papers into Paper Fusion Reactor and generate new research directions from the same library you read from and curate every day.

What You Can Do

Capture and organize papers

• Import from arXiv abstract URLs, arXiv PDF URLs, direct PDF URLs, or manual metadata entry.
• Drag local PDFs directly into the app window.
• Extract metadata from PDFs when possible, then enrich with arXiv and Crossref data.
• Avoid duplicate imports by matching normalized source identity.
• Store managed PDFs in the default app folder, a custom local folder, or a remote SSH destination.
• Watch a local storage folder and auto-ingest newly copied PDFs.

Manage reading flow

• Work from dedicated Today, Inbox, Queue, and Library screens.
• Reorder queue items, snooze papers, and move papers across inbox, scheduled, reading, done, and archived.
• Schedule native macOS reminders for daily review and due or overdue papers.
• Search the library by title, author, abstract, venue, DOI, and tags.

Read and annotate in-app

• Open papers in an in-app PDFKit reader.
• Search within the PDF, jump pages, switch display modes, and toggle thumbnail and outline sidebars.
• Highlight passages, attach notes, and reopen annotations from the margin.
• Ask questions about a selected passage with Ask AI.
• Run Paper Elf as an ambient critique companion while you read.

Generate reusable outputs

• Create AI-generated Paper Cards from the paper detail view.
• Save Paper Cards locally and copy them as text or HTML.
• Use Paper Fusion Reactor to combine multiple papers into idea prompts.
• Capture structured feedback inside the app and export it to the clipboard.

Work with agents

• Open an embedded terminal inside PaperMaster and run local tools like codex.
• Bootstrap an agent workspace with an app-specific AGENTS.md and the built-in papermaster-agent-ops skill.
• Use a watched import directory so agents can drop PDFs into PaperMaster for fast ingestion.

Local-First Behavior

• Library data is stored locally with SwiftData.
• Cached PDFs and generated Paper Card exports are written to local storage.
• Managed PDFs can stay local or be copied to a configured remote SSH target.
• Feedback entries stay local until you copy them out.
• AI provider keys and SSH passwords are stored in the macOS Keychain.
• Network access is only needed for metadata lookup, PDF downloads, remote storage, and optional AI features.

Requirements

• macOS 14 or later.
• Xcode Command Line Tools with a working swift executable.
• Internet access if you want arXiv/Crossref enrichment, hot paper discovery, remote paper storage, or AI-backed features.

The standalone app bundle flow is written for Apple Silicon builds.

Build and Run

Build the app bundle from the project root:

./Scripts/build-app.sh release

This produces:

dist/PaperMaster.app

For a debug bundle:

./Scripts/build-app.sh debug

For development:

./Scripts/swift-overlay.sh test
./Scripts/swift-overlay.sh run PaperMaster

Open Package.swift in Xcode for the normal macOS debugging workflow.

AI Provider Setup

PaperMaster uses one OpenAI-compatible provider configuration for Ask AI, Paper Elf, Paper Cards, Fusion Reactor, and optional import auto-tagging.

1. Open Settings.
2. Set the provider Base URL.
3. Set the Model name.
4. Save the API key to Keychain.
5. Optionally enable Automatically generate tags on import.

Codex Inside PaperMaster

The embedded terminal bootstraps a PaperMaster-specific agent workspace with:

• PAPERMASTER_AGENT_WORKSPACE
• PAPERMASTER_AGENT_SESSION_DIR
• PAPERMASTER_AGENT_IMPORT_DIR
• PAPERMASTER_AGENT_EXPORTS_DIR
• PAPERMASTER_AGENT_SKILLS_DIR

Typical flow inside the terminal:

codex

Then ask naturally:

Import this paper into PaperMaster: https://arxiv.org/abs/2505.13308

Or call the skill explicitly:

Use papermaster-agent-ops to import this paper into PaperMaster: /path/to/paper.pdf

For local-storage setups, the fast path is simple: the agent downloads or copies the PDF into PAPERMASTER_AGENT_IMPORT_DIR, and PaperMaster ingests it automatically.