Papers

An AI reading companion for research papers. Define what you are working on, get relevant papers, skim them Andrew Ng–style, read with an explainer that knows the whole paper, track where you stopped, quiz yourself when you finish, ask "where did I read this idea?", and follow reference chains. It runs on your computer; your papers and notes stay there. See SPEC.md for the design.

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

papers opens http://localhost:8000 in your browser. Options: --port 9000, --data D:\Papers (where the database and PDFs live), --no-browser, --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

docker compose up -d

Then open http://localhost:8000. Your library is kept in the papers-data volume. 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

Choosing an AI model

Settings > AI model has one list of providers; each is set up the same way (key if it needs one, then List models and pick one). 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. Keys are kept in your system's keychain (Windows Credential Manager, macOS Keychain, or the Secret Service on Linux), so you paste each one once; Settings shows which provider has a key saved (its last four characters) and can forget it. Where there's no keychain (Docker, servers) they stay in the app's database. Keys are never sent back to the page.

With a subscription the app runs the official CLI on your computer (claude -p or codex exec, with no tools), 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. Switch the chat to Deep and the AI first reads the sections, looks at the figures and checks your notes and library before it answers; ask it to and it saves notes, words and highlights, or adds a paper from the references (each with Undo). Deep mode works with Claude (subscription or API key) and with models that support tool calling; in More options, tick This model can see images if yours does, and Interactive pages to let the AI write small demos that run in a sealed frame.

Library folder

In Settings, choose a folder (Choose… opens a folder browser with your usual folders and drives) and the app keeps a copy of your library there: one folder per goal (Unsorted for the rest), each paper as Author et al. Year - Title.pdf with a .md notes file next to it (key points, explanations, quiz, [[links]] to related papers, so Obsidian shows them as a graph). PDFs dropped into its Inbox folder are imported within about 10 seconds.

Settings from the environment

Contributing

See CONTRIBUTING.md: how the code is laid out, how to run it and the tests, and where to start for common changes.

License

MIT