Download & install

Running in five minutes

There's nothing to compile and no service to sign up for. Get the folder, double-click the app, follow the tutorial — Reading Room sets itself up around you.

The short version: get the folder (Git clone or a release download) → double-click ReadingRoom.app (macOS), ReadingRoom.bat (Windows) or ReadingRoom.sh (Linux) → the tutorial opens and hands you to Setup. Everything else below is detail.

Get the files

Two ways — and both update in one click from inside the app. A signed one-click installer will come later.

Recommended

Clone with Git

One paste, and you never need a terminal again. The line below clones Reading Room into your home folder — a safe spot (not Desktop, not OneDrive), so the app just works — and opens the folder for you. Then double-click ReadingRoom.app / ReadingRoom.bat.

# macOS — paste into Terminal:
cd ~ && git clone https://github.com/FrancescoPiatti/Reading-Room.git ReadingRoom && open ReadingRoom

# Windows — paste into PowerShell:
cd ~; git clone https://github.com/FrancescoPiatti/Reading-Room.git ReadingRoom; explorer ReadingRoom

# Linux — paste into a terminal:
cd ~ && git clone https://github.com/FrancescoPiatti/Reading-Room.git ReadingRoom && cd ReadingRoom

Updating is one click. Avatar menu → Updates checks the clone's Git remote for a newer version and pulls it in as a fast-forward; if it can't fast-forward (you've edited the code), your assistant finishes the job with /update. You choose Later, Skip this version or Update now — and an update never touches your library: your papers, notes, settings and PDFs are yours, not the repo's.

Needs Git. On a fresh Mac, the first git run offers to install Apple's command-line tools — accept and re-paste.

Download a release

No Git, no account setup: open Releases and take the ZIP for your platform — it ships with the app's components already built, so the first launch opens straight away instead of installing anything. (Today that is the macOS build for Apple silicon; on Windows and Linux, clone for now — updates work the same either way.) Unzip it somewhere sensible (a plain local folder like ~/ReadingRoom — not Desktop or a cloud-synced folder).

Updates work here too. Avatar menu → Updates follows the published releases — never a half-finished change — downloads the new build and replaces the app's own files in place: the same Later / Skip this version / Update now choice, and your library, notes and settings are never touched. Either way, Reading Room writes a backup of your library before it updates.

Coming later: a signed one-click installer for macOS and Windows. Until then, a Git clone or a release download are the two supported paths — both on macOS, Windows and Linux.

What you need

Three things, and only the first two for the static site. All free.

Python 3.8+ — the build

Builds your site invisibly under the hood — pure standard library, no packages, no pip, no virtualenv. You never run it yourself; the app and your AI do.

macOS Usually already there — check with python3 --version. If missing: xcode-select --install or python.org.
Windows Install from python.org and tick "Add python.exe to PATH", or winget install Python.Python.3.12. Check with python --version.

An AI coding assistant — the author

Reports are written by your own AI coding assistant — Claude Code, Codex CLI, or Gemini CLI — running inside the app under the subscription you already have. No API key, no API billing: Reading Room never calls a paid API, and nothing leaves your machine except the assistant's own traffic, a version check against GitHub on launch (no library data is sent), arXiv when you open a PDF, and MathJax's CDN for equations. You need just one of the three (you can switch per run inside the app); install it, then run it once from a terminal to log in.

Claude Code

docs

# with npm (macOS / Windows / Linux):
npm install -g @anthropic-ai/claude-code

# or the native installer — macOS / Linux:
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell:
irm https://claude.ai/install.ps1 | iex

Then run claude once and log in with your Claude account (Pro or Max).

Codex CLI

docs · GitHub

# with npm (macOS / Windows / Linux):
npm install -g @openai/codex

# or, on macOS, with Homebrew:
brew install --cask codex

Then run codex once and sign in with ChatGPT (Plus, Pro or Team).

Gemini CLI

GitHub · docs

# with npm (macOS / Windows / Linux):
npm install -g @google/gemini-cli

# or, on macOS, with Homebrew:
brew install gemini-cli

Then run gemini once and sign in with Google.

The npm route needs Node.js — step 3, which the app needs anyway. Whichever assistant you pick, make sure it launches from a terminal in any folder (Terminal on macOS; PowerShell or Command Prompt on Windows) — the app finds it from there.

Node.js 18+ — the app

Powers the Reading Room app — the flow buttons, the integrated AI terminal behind them, live rebuilds, backup and updates. Only skip it if you just want to browse the static site.

macOS nodejs.org LTS or brew install node. If the terminal component needs compiling: xcode-select --install.
Windows nodejs.org LTS installer or winget install OpenJS.NodeJS.LTS. If the terminal component needs compiling: the free Build Tools with "Desktop development with C++".

Then: launch it, and make it yours

Launch the app

Double-click ReadingRoom.app (macOS), ReadingRoom.bat (Windows) or ReadingRoom.sh (Linux — it also adds a menu entry on first run). The first run installs its dependencies (a minute or three — it tells you; a release download has them already) and offers a Reading Room shortcut — on your Desktop or in your Applications folder (Start Menu on Windows); after that every launch starts a loopback-only server in the background and opens the app window: the catalogue, the Analyze button and its ▾ flows, live rebuilds, in-app PDFs and note-editing. (Prefer a terminal? cd workmode && npm start runs the same thing in the foreground with visible logs.)

macOS notes: the app is unsigned, so on first open right-click it → Open (or run xattr -dr com.apple.quarantine ReadingRoom.app). Keep the folder in a plain local place like ~/ReadingRoom — Desktop, Documents, and cloud-synced folders (OneDrive/iCloud/Dropbox) are privacy-protected, so macOS may block the app's file access (the app shows a dialog pointing you to System Settings → Privacy & Security), and cloud sync can evict file contents, which stalls the server at startup.

First run: make it yours

A short tutorial opens, then hands off to Setup — pick your field(s), focus views, and defaults; the app applies everything for you through your assistant. Then click Analyze paper, paste an arXiv id, and watch your first report land. Two example papers ship in the catalogue (Attention Is All You Need and Hornik's universal-approximation theorem) so you can see finished reports; remove them once you've added your own (/remove <id> in the Terminal drawer).

Optional: browse without the app — or host it

Everything the app builds is a plain static site: double-click docs/index.html and the catalogue opens in any browser — search, filters, reports, graph, all client-side, fonts and libraries self-hosted, so it works offline and nothing pings a CDN about what you read. To put it online for free: push to GitHub, then Settings → Pages → deploy from branch, folder /docs.

Back to overview Now see how to use it