The macOS PDF reader and library manager for people who search, highlight, cite, and file research papers. It is the reader I wished I had years ago.
PaperShelf is under heavy development. It is functional, but releases can change stored preferences and behavior.
brew tap jonaprieto/papershelf
brew trust --cask jonaprieto/papershelf/papershelf
brew install --cask papershelfThe cask installs the latest release. Builds are ad-hoc signed while notarization is on the roadmap, so the first launch may require right-click, Open in Finder.
brew update
brew upgrade --cask papershelfPaperShelf shows an update notice beside its version when a newer release is available. Use Check for updates from the app menu, About or command palette. Automatic release checks are configurable in General settings. Local development builds default to manual remote checks and also notice completed builds on your Mac. Notices link to a release or reveal a local build; installation and relaunch stay under your control.
Build the app bundle:
./build.shInstall a fresh local build in /Applications:
./build.sh --installPaperShelf has no third-party Swift package dependencies. It runs on macOS 14 or later.
- Reads PDFs in a focused reader with full screen, page navigation, contrast modes, and notes that stay beside the passage they describe.
- Searches filenames, metadata, extracted text, folders, tags, pages, and projects.
- Highlights passages with customizable meanings per library, folder, project, or paper.
- Writes a generated Markdown companion beside a PDF, with PDF annotations as the source of truth.
- Reviews safe filename changes before applying them, keeps originals when requested, and finds duplicate documents without guessing that similar names are identical.
- Builds BibTeX and connects a local MCP server to ChatGPT without uploading the library.
In a source build, use File > Open Website (Command-L), the globe toolbar button, or the command palette. Navigate to an article, then choose Save copy. This saves the full loaded page as a paginated A4 PDF, the web archive, and a BibTeX companion under PaperShelf's Application Support folder. The reading copy joins the catalogue and uses the same notes, highlights, search, contrast and split controls as other documents. Selecting text on the live page and choosing a highlight colour saves and marks that passage in the reading copy. Ambiguous text matches ask you to select in the saved copy.
An article's Open live button opens its website in the same pane, including beside a PDF. Choose Save new version to keep a new version. Existing copies and their annotations are retained. A snapshot includes content loaded at capture time; it does not crawl linked pages or fetch material hidden behind a site's login or an unopened section.
Citation facts come from Highwire, Dublin Core, Open Graph and schema.org metadata supplied by the page. Missing authors and publication dates stay missing. The citation includes the source URL and capture date; review it in the Cite inspector before publication. Saving a new version reads fresh metadata and writes a new citation without changing the older copy's citation. A supplied revision date is retained separately from publication. Capture waits for MathJax and web fonts to finish rendering. Equations retain their visual appearance; equations drawn as images or SVG may not have selectable text.
Ask AI on selections, marks and the notes export bar uses the API endpoint and model in Settings. It shows the text and destination before Send question. The ChatGPT handoff is an additional option; it is not required for these reading questions.
To use a local model, start its server, then choose LM Studio or llama.cpp in Settings > AI & spend. Set the model ID and test the connection. Localhost can use an empty API key; local credentials are stored separately from cloud credentials.
Turn off AI features in Settings > General to hide model tools, cancel pending model requests, and block ChatGPT handoffs and MCP tool access. Reading, annotations, local search and citation metadata lookup remain available. Requests already sent cannot be recalled.
- Notarized and signed releases
- Stable 2.0 storage and plugin interfaces
- Better OCR and reading-project workflows
- Upstream Homebrew Cask submission when the project meets its requirements
