Papers

An AI reading companion for research papers.
Find the right papers for what you're working on, read them with an AI that knows the whole paper, and remember what you read.

uvx papers-app

About

Reading research papers is slow when you're new to a field: you don't know which papers matter, in what order to read them, or what half the words mean. Papers is the companion for that.

• Start from a goal. Say what you're trying to understand. Papers searches Semantic Scholar and arXiv and the AI suggests a reading roadmap: the basics first, then the core methods, then the newest work, with why each paper and about how long it takes. Tick the ones you want (or keep them all) and they're added, PDFs included.
• Read with an AI that has the whole paper. Select a passage and press Explain, Simplify or Translate, or just ask. Answers cite the paper's sections and figures, write formulas properly, and can draw charts and small interactive widgets. Every question is a conversation you can come back to.
• Remember it. Key points for every paper, its hard words marked in the text, a quiz when you finish, spaced review, and Recall: describe an idea in your own words and find where you read it.

It runs on your computer. Your library (papers, notes, highlights, conversations) is a folder on your disk, and you choose the AI: your Claude or ChatGPT subscription, an API key, or a model running locally with Ollama or LM Studio.

A tour

Ask about a figure. The AI looks at the figure and points at the parts it is talking about.	Play with a formula. Answers can draw plots and small widgets with sliders, for any field.
Goals. Each goal keeps its papers together, shown by their first pages, with one line on what each says.	Recall. "Where did I read that?" Searches every paper, your notes and the explanations you asked for.
Reading roadmap. For each goal, the best papers in reading order. Pick some or all; PDFs download for you, and your progress shows as you read (Start here, Next up).	Reader. Select a passage to have it explained, simplified or translated, beside the page.
Each paper at a glance. Key points, figures and tables, its vocabulary, your notes, and its references (follow one to grow a chain on the Map).	Light, dim or dark, with the PDF pages dimmed to match.
Quick or Deep. Quick answers at once from the paper; Deep lets the AI search it, read sections, look at figures and check your library first.

Install

With Python 3.11 or newer, one command (like npx for Node):

uvx papers-app

or install it to keep it around, then start it with papers:

pipx install papers-app

The first time, a short setup in the terminal asks three things, so it's clear from the start where everything goes:

1/3  Your library        where the database, PDFs and figures are kept (one folder)
2/3  A folder to browse  optional: each paper's PDF and Markdown notes, for your file manager or Obsidian
3/3  The AI model        provider, key (kept in your system's keychain) and model, then a quick check

Then papers opens http://localhost:8000 in your browser. Everything can be changed later in Settings, or with papers setup. Options: --port 9000, --data D:\Papers (use this data folder), --no-browser, --no-setup, --host 0.0.0.0 (reach it from other devices on your network; there is no login, so only on networks you trust).

With Docker

The image is published on GitHub's registry, so one command pulls it and starts the app:

docker run -d --name papers -p 8000:8000 -v papers-data:/data ghcr.io/hbouanane/papers:latest

Then open http://localhost:8000 and choose the AI in Settings. What each part means:

To update: docker pull ghcr.io/hbouanane/papers:latest, then docker rm -f papers and the same docker run again (the volume keeps your library). From a clone you can also build it yourself with docker compose up -d; see docker-compose.yml to use a folder on your computer for the library folder, or a model running on your computer (Ollama, LM Studio). Subscriptions (Claude, ChatGPT) need their app on the same computer, so in Docker use an API key or a local model.

From the source

git clone https://github.com/hBouanane/papers && cd papers
python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"     # macOS/Linux: .venv/bin/pip
.venv/Scripts/papers

Where everything is kept

Settings › Where everything is kept shows all of it, with sizes:

Choosing an AI model

Settings › AI model has one list of providers, each set up the same way: its key if it needs one, then List models and pick one. Changes save as you make them, and Check it works sends one short question to make sure. Each provider keeps its own key and model, so you can switch freely.

• Use your subscription: Claude (Pro, Max) through Claude Code, or ChatGPT (Plus, Pro) through OpenAI's Codex CLI (npm install -g @openai/codex, then codex login). Both run on your computer with your own account, for your own use: don't host the app for others on your subscription.
• Pay per use with an API key: Anthropic, OpenAI, Google Gemini (has a free tier), Mistral, Groq, or OpenRouter (hundreds of models).
• On this computer: Ollama or LM Studio. Free, and nothing leaves your machine.
• Other: any OpenAI-compatible server (vLLM, llama.cpp, a company gateway), by its address.

Small local models can't read a whole paper; More options can send just its beginning. With a subscription the app runs the official CLI on your computer (claude -p or codex exec), which signs in with your own account; usage counts toward your plan. The app never reads or stores those credentials. PAPERS_CLAUDE_BIN and PAPERS_CODEX_BIN point at a specific binary if needed.

Asking the AI

Select text in a paper and press Explain (a short lesson: the problem, the idea, the formula read slowly, a worked example, why it works, where it connects in the paper), Simplify (the same passage in plain English) or Translate. Each starts a conversation you can keep going; History keeps them per paper, and Add to chat attaches more passages. Answers can contain formulas, clickable citations ([§3.4], [Fig. 1]), charts, diagrams, the paper's own figures with "look here" boxes, and interactive widgets.

The chat has two modes:

The buttons on a selection (Explain, Simplify, Translate) answer Quick; Deeper under an answer goes Deep. In Settings › What the AI can do, Interactive pages lets the AI write small demos that run in a sealed frame (no access to the app, your files or the internet).

Settings from the environment

Contributing

Contributions are welcome: bug reports, ideas and pull requests. CONTRIBUTING.md explains how the code is laid out, how to run it and the tests (no keys needed: AI and network calls are faked), and where to start for common changes. Please follow the code of conduct. Changes are listed in CHANGELOG.md; the design is in SPEC.md and DESIGN.md.

Found a security problem? Please report it privately: see SECURITY.md.

License

MIT