Ream: A Paper Manager

Setup

1. Install dependencies:

pip3 install -r requirements.txt

2. Create a config file by running:

cp config.default.yaml config.yaml

Edit config.yaml as appropriate.

3. Create the SQLite database:

./create-db

This creates an empty database in the location specified by config.yaml.

4. Run the app (will use port 5538 by default)

python3 app.py

Paper lists and keyboard navigation

The home page has three paper lists:

• In progress contains queued papers that have been opened with the local PDF viewer. It is sorted by the most recently opened date. Opening a queued paper locally adds or moves it to the top immediately.
• Queued contains papers that have not yet been marked as read.
• Read contains completed papers and their notes.

Press p, q, or r to focus the In progress, Queued, or Read list. Press n to cycle through all three. The complete keyboard shortcut list is available from the help button in the Ream header.

Open papers in a Windows PDF viewer

Ream can hand a paper to a small Windows companion that downloads it into a local library and opens it in either the default PDF application (for example, Drawboard PDF) or Xournal++.

Update an existing database

After pulling this feature, run this once from the Ream directory:

./migrate-add-last-opened

New databases created with ./create-db already contain the required columns.

Install the Windows companion

Open PowerShell in the windows-companion directory and choose one setup:

# Use the Windows default PDF application
.\Install-ReamPdfCompanion.ps1

# Use Drawboard PDF directly (it does not need to be the default PDF application)
.\Install-ReamPdfCompanion.ps1 -Viewer Drawboard

# Or use Xournal++
.\Install-ReamPdfCompanion.ps1 -Viewer Xournal

If Xournal++ is installed elsewhere, pass its executable path:

.\Install-ReamPdfCompanion.ps1 -Viewer Xournal `
  -XournalPath "C:\Path\To\xournalpp.exe"

The installer registers the ream-pdf:// protocol for the current Windows user and creates a local library at Documents\Ream Papers. It does not require administrator access. The protocol handler runs in the background without opening a PowerShell window.

To choose a different library folder, pass -LibraryDirectory. For example:

.\Install-ReamPdfCompanion.ps1 -Viewer Drawboard `
  -LibraryDirectory "C:\Users\you\OneDrive\Documents\Ream Papers"

In Ream, click Local beside a paper title or press o on the selected row. The first browser launch may ask for permission to open the Ream PDF Companion. The normal title link and e shortcut continue to open the source URL in the browser.

Downloaded papers are stored directly in the configured library folder. Every paper uses its persistent Ream identifier in a filename such as Jia - First Seven Words Of The Paper Title - ream-AbCdEf0123456789_-wxyz.pdf. The first author's last name leads the filename, and the title is limited to seven words and may be shortened further to keep filenames manageable. When Xournal++ is selected, the companion opens the matching .xopp file if one exists; otherwise it opens the PDF.

When upgrading an existing installation, add stable local identifiers before starting Ream, then reinstall the Windows companion:

./migrate-add-local-id

Credits

Icons were taken from https://primer.style/octicons/.