A Chrome extension (Manifest V3) for asking Claude questions about a research-paper PDF. Answers come back with verbatim supporting quotes, which are highlighted in the PDF, with one color per question.
- Opens PDFs in a bundled copy of Mozilla's pdf.js viewer (v6.4.299), because Chrome's built-in viewer can't be scripted.
- A sidebar shows your questions, Claude's short answers and 1–3 quotes per answer. Click a quote to scroll to its highlight and flash it.
- Quotes are matched to the text layer by a matcher that tolerates hyphenation, ligatures, smart quotes, dashes, line breaks, page breaks and small wording differences. Approximate and low-confidence matches are labeled in the sidebar.
- Tick Search the web before adding a question to let Claude also search the web for it, for example for later work, released code or the current state of a result. Answers then list the web pages they rely on, each with a link and a supporting quote. Only pages that a search actually returned are shown.
- Tick Free-form answer for requests that don't fit a short quoted answer, such as "list every dataset as a Markdown table" or "extract the hyperparameters as JSON". The whole input box becomes one request, Claude answers in the format you ask for, and quotes become optional (it still adds them where they directly support the answer). Free-form answers keep their line breaks and have a Copy answer button.
- Ask about a passage. Select text in the PDF and click Ask about selection. The passage is attached to the next questions you add, so "what does this mean?" or "how is this computed?" is about that passage, and Claude reads the rest of the paper for context. The card shows the passage; click it to go to its page.
- Implementation prompts. The Implement tab writes a prompt for Claude Code that reimplements what the paper built. Claude first lists the models, architectures, algorithms or systems the paper implements; if there are several, you pick one. The prompt specifies the architecture, every equation, the hyperparameters, data, training and evaluation with page references, lists the details the paper leaves out with a recommended choice for each, gives the reported results as targets, and lays out milestones with checks. Add optional notes (for example "PyTorch, one GPU") and tick Search the web to let Claude find and read the official code, project page or appendix; the pages it used are listed. Copy prompt or Download .md, then paste it into Claude Code in an empty repository. With the Claude Code backend (below), Paper Q&A does that for you: it creates a project folder with the prompt and the paper and starts Claude Code on it in a terminal window.
- Claude Code instead of an API key. On macOS and Linux, Paper Q&A can send its requests to your own Claude Code installation, so it uses your Claude Code login and plan instead of an API key. See Use Claude Code instead of an API key.
- Export annotated PDF saves a copy with the highlights written in as real PDF Highlight annotations, so they show in Acrobat, Preview, Chrome and other readers.
- Export Markdown saves the questions, answers and quotes, with page numbers and match notes, as a
.mdfile for your notes. - Citation previews. Click a citation such as
[41]or(Peters et al., 2018)and a card shows the cited paper instead of jumping to the reference list: title, authors, venue and year, citation count, a one-sentence summary (from Semantic Scholar), the abstract, and links to Google Scholar, the data source, arXiv, the DOI and the PDF. The lookup starts as soon as you point at a citation, so the card is usually ready when you click. Open in Paper Q&A opens the cited paper in a new tab. Go to reference still jumps to the bibliography entry, and Ctrl/⌘-click keeps the old behavior. Numbered citations work even in PDFs whose citations aren't links, such as some proceedings archives' copies. - Paper info. The ⓘ button in the viewer's toolbar shows the same card for the open paper, with a Copy BibTeX button.
- Default PDF viewer. Set "When a PDF opens" to Always (or click Always on the banner) and PDFs open straight in Paper Q&A, including local files. The address bar shows the PDF's own URL, as
chrome-extension://<id>/https://arxiv.org/pdf/…, so you can still read, copy and reload it. To go back, click Use Chrome's PDF viewer again at the bottom of the sidebar or on the options page. - Results are cached per file (by SHA-256 hash). Reopening a paper restores its questions, highlights and implementation prompt without a new API call.
Paper Q&A is an independent project and is not affiliated with or endorsed by Anthropic.
From the Chrome Web Store: coming soon.
From a release: download paper-qa-<version>.zip from the latest release and unzip it. Then follow the steps below, selecting the unzipped folder.
From source: no build step is needed. The repository already contains the vendored libraries.
- Open
chrome://extensions. - Turn on Developer mode (top right).
- Click Load unpacked and select the folder that contains
manifest.json. - Optional, for local PDFs: on the extension's Details page, turn on Allow access to file URLs. Without this,
file://PDFs can't be read. You can still drag a file into the viewer or use its open-file button.
- Click the extension's toolbar icon and choose the ⚙ in the sidebar, or right-click the icon and choose Options.
- Paste your Anthropic API key (create one at console.anthropic.com). It is stored only in
chrome.storage.local, used only by the background service worker, and sent only toapi.anthropic.com. - Pick a model. Test key & load models checks the key and lists every model it can use.
claude-opus-5-5(default): best answers, $4 per million input tokens.claude-sonnet-5-5: faster and cheaper.claude-haiku-5-5: fastest and cheapest.claude-fable-5-1: most capable, most expensive.
- Optionally set Effort (default: medium) and choose what happens when a PDF opens: offer, always open (Paper Q&A becomes Chrome's PDF viewer), or do nothing.
- Optionally paste a free Semantic Scholar API key for citation previews and paper info. They work without one: Semantic Scholar's keyless rate limit is often used up, and lookups then come from Crossref, OpenAlex and arXiv, without the one-sentence summary.
A typical 10–15 page paper is around 15–20k tokens, which is a few cents per question batch with Opus 5.5. The sidebar shows an estimate for each paper. The paper text is sent with prompt caching, so follow-up questions on the same paper within a few minutes cost much less.
A browser extension can't start programs itself, so this needs a small helper (native-host/) that Chrome starts through native messaging. It needs macOS or Linux, Node.js 20+, and Claude Code installed and logged in (run claude once).
- On the options page, set How to reach Claude to Claude Code on this computer.
- Copy the install command shown there and run it in a terminal from this repository's folder (clone it, or download the source from the latest release). It looks like
./native-host/install.sh <extension-id>. It copies the helper to~/.paper-qa/and registers it for Chrome (and Chromium, Brave and Edge if they're installed)../native-host/install.sh --uninstallremoves it. - Click Check Claude Code, choose a Folder for implementation projects (default
~/paper-qa-projects) and Save.
Questions and the Implement tab then run claude -p with the model and effort chosen on the options page. Its usage counts against your Claude Code plan, and no API key is needed. When the Implement tab has written a prompt, it creates <folder>/<system-name>/ with IMPLEMENTATION_PROMPT.md and paper.pdf and opens a terminal window running Claude Code there, asked to carry out the prompt. On macOS that is Terminal; on Linux the first of x-terminal-emulator, gnome-terminal, konsole, xfce4-terminal, kitty, alacritty and xterm that exists. To use another terminal, set PAPER_QA_TERMINAL in ~/.paper-qa/claude-code-host to a program that runs the shell script it is given. Start in Claude Code starts it again on a new folder.
- Open any PDF in Chrome. Paper Q&A detects it by URL or by
Content-Type: application/pdf, soarxiv.org/pdf/…URLs work. It then shows an Open in Paper Q&A banner (or a notification if the banner can't be shown) and a "Q&A" badge on the toolbar icon. Clicking the toolbar icon also opens the current PDF. - You can also right-click a link and choose Open PDF in Paper Q&A.
- Click a citation in the paper to preview the cited paper, or the ⓘ toolbar button for the open paper. Esc or a click elsewhere closes the card. Turn previews off on the options page to make citations jump to the reference list again.
- Type one or more questions, one per line, and press Add (⌘/Ctrl+Enter). Then press Find answers. Only unanswered questions are sent. Re-ask all sends them all again.
- Questions added with Search the web ticked are tagged "web". Claude may run up to 5 searches per request for them, billed by Anthropic at $10 per 1,000 searches on top of tokens. Your organization's admin can turn web search off in the Claude Console; the sidebar then explains the error.
- Quote badges in the sidebar:
- no badge: exact match.
≈ 93%: close match (for example, the model changed a word).⚠ low confidence: weak match. The highlight also gets a striped pattern; check it yourself.not found in text: no highlight was made.
manifest.json
background/service-worker.js PDF detection, offer banner, context menu, message routing
background/claude.js Messages API client: streaming, retries, error mapping
background/claude-code.js the Claude Code backend: talks to the native helper
native-host/ the native messaging helper that runs claude, and its installer
background/scholar.js paper lookups (Semantic Scholar, Crossref, OpenAlex, arXiv) for previews and paper info
shared/models.js model list, defaults, settings
shared/prompt.js system prompt, JSON schema, response validator
shared/implement.js prompts, schemas and validators for the Implement tab
lib/matcher.js quote matcher (pure ES module, also runs in Node)
lib/references.js finds a citation's bibliography entry and the open paper's identity
src/viewer/boot.mjs runs before pdf.js to take over document loading
src/viewer/qa.mjs, qa.css sidebar, highlighting, cache, export trigger
src/viewer/papers.mjs citation preview cards and the toolbar's paper info button
src/viewer/implement.mjs the Implement tab: systems in the paper, Claude Code prompt
src/viewer/dom.js h(), the small DOM helper the viewer builds its UI with
src/viewer/export.js writes /Highlight annotations with pdf-lib
src/viewer/markdown.js renders questions, answers and quotes as Markdown
options/ settings page
vendor/pdfjs/, vendor/pdf-lib/ pinned upstream builds (pdf.js 6.4.299, pdf-lib 1.17.1)
scripts/vendor.sh re-downloads vendor/ and patches viewer.html (one command)
tests/matcher-test.mjs matcher stress test on real arXiv PDFs
tests/references-test.mjs citation-to-reference test on real arXiv PDFs
tests/e2e.mjs end-to-end test in headless Chrome (mocked APIs)
tests/native-host-test.mjs the native helper over native messaging, with a fake claude
scripts/package.sh builds dist/paper-qa-<version>.zip for the store
scripts/cws-publish.mjs uploads a package to the Chrome Web Store (used by CI)
store/ store listing text, screenshots and promo images
API request. The viewer extracts every page's text with pdf.js and sends it to the service worker over a long-lived port. The service worker calls POST https://api.anthropic.com/v1/messages with these headers: x-api-key, anthropic-version: 2023-06-01 and anthropic-dangerous-direct-browser-access: true. The request streams the response, asks for structured JSON output, and sets fallbacks: "default", which reruns the request on another model if a safety classifier declines it (Opus, Sonnet and Fable models only). The reply must match this schema:
{
"answers": [
{
"question_index": 1,
"answerable": true,
"answer": "Short answer.",
"quotes": [{ "text": "Verbatim sentence from the paper…", "page": 4 }],
"web_sources": []
}
]
}A question about selected text is marked [about selection] and followed by the passage, as <selection page="N">…</selection> (at most 6,000 characters), in the uncached part of the message. Questions with Free-form answer on are marked [free-form]: their answer may take any format and length, quotes may be empty even when answerable is true, and the request allows 32k output tokens instead of 16k. When a question has web search on, the request also includes Anthropic's server-side web_search tool (web_search_20260209, or the basic web_search_20250305 for models without dynamic filtering) and the question is marked [web search allowed]. Claude then fills web_sources with { url, title, quote } entries. The service worker rebuilds the streamed content blocks so a paused turn (pause_turn) can be resumed, records every search result and citation URL, and drops any web source whose URL no search returned. When the paper doesn't answer a question, answerable is false, answer says what the paper does or doesn't cover, and quotes is empty. The reply is validated; if it is malformed, the extension retries once and shows Claude what was wrong. Errors get clear messages: missing or invalid key, unknown model, rate limits (with automatic retry when the wait is short), API overload, refusals, and PDFs too long for the model's context window (checked before sending as well).
Implementation prompts. The Implement tab makes two requests through the same port and request loop as questions, each with its own system prompt and JSON schema. The first sends the paper and asks for { systems: [{ name, kind, summary, pages }] }: the paper's own contributions that can be built, with variants of one model merged and baselines left out. With one system, the second request follows at once; with several, the sidebar asks which. The second sends the paper, the chosen system as <target>, the other systems (so Claude knows what not to build), and your notes, and asks for { prompt, web_sources }, allowing 64k output tokens. With Search the web ticked, it includes the web_search tool (5 uses) and the web_fetch tool (web_fetch_20260209, or web_fetch_20250910 for models without dynamic filtering; 8 uses), and the target is marked [web search allowed]. Web fetch can only open addresses that already appear in the conversation, such as search results. As with answers, a listed web page is kept only if a search returned it or a fetch opened it. Both results are cached under impl:<hash>.
Claude Code backend. The service worker opens chrome.runtime.connectNative("com.paperqa.claude_code") for each request, which starts native-host/paper-qa-host.mjs. The helper runs claude -p --output-format stream-json in an empty temporary folder, with the request's system prompt replacing Claude Code's own (--system-prompt), the same JSON schema (--json-schema), --model and --effort from the options page, no MCP servers, no saved session, and no tools except WebSearch and WebFetch when the web is allowed. The paper and questions go in on stdin. The helper forwards progress, the pages that searches returned and fetches opened, and the final structured output, which the same validators check as API replies; a malformed reply is retried once. Server-side fallbacks, prompt caching and cost estimates are API features, so they don't apply. A launch writes the project folder and a small shell script that changes to it and runs claude "Read IMPLEMENTATION_PROMPT.md and carry it out. …", and opens it in a terminal.
Matcher. Both the page text and each quote are reduced to a key: NFKC-normalized (this expands ligatures like fi and turns math letters like 𝑥 into plain letters), accents stripped, lower-cased, and only letters and digits kept. Whitespace, line breaks, hyphenation, dashes and quote marks therefore can't cause a mismatch. Every key character records the text-layer item and character offset it came from. The matcher then tries, in order:
- An exact key match. When there are several, it picks the one nearest the page the model gave. Matches can span any number of spans and cross page breaks.
- A match that ignores digits, which covers dropped citation numbers like
[12]and footnote markers. - If the quote contains
..., a match of each piece separately, but only when the quote doesn't match as a whole (...can be literal text, such as table-of-contents leaders). - A fuzzy match. Candidate regions are found by k-gram voting, then the quote is aligned against each region with an edit-distance alignment. A score of 0.9 or more counts as approximate, 0.7–0.9 as low confidence, and anything lower as not found.
The matched key range is mapped back to (page, item, start, end) segments. When pdf.js renders a page's text layer (on scroll or zoom), the affected spans are split and the matched characters are wrapped in colored <span>s. Highlights are reapplied every time a page re-renders.
Citation previews and paper info. A click on an internal link is caught before pdf.js follows it. The link's destination is resolved to a page and position. If it is a citation, the bibliography entry is read from the text items below that position, up to where the next entry starts. A citation is a hyperref cite.* destination, or a target after the "References" heading that looks like an entry. In PDFs without citation links, numbered citations in the text ([7], [20, 21], [3–9]) are found under the pointer with caretPositionFromPoint and lead to the entry labelled [n] after the "References" heading. This only happens before that heading, on pages that have no citation links. Entries are recognized by labels like [12], by hanging indents, and by entries that continue in the next column or on the next page. From the entry's text the viewer takes a DOI, an arXiv ID or a title guess: the first sentence after the author list, skipping a year, or a quoted title. The service worker runs two lookups at once and shows the first paper found:
- The Semantic Scholar Graph API:
GET /paper/DOI:…or/paper/ARXIV:…, otherwise/paper/search/match?query=<title>. Its keyless rate limit is shared by everyone and is often used up, so without a key it gets one attempt (with a key, one retry). - An open route that needs no key. Crossref
query.bibliographicis given the whole entry text, and arXiv's API gets a title search. That second search covers preprints and venues without DOIs, such as ICLR. The DOIs found, including arXiv DOIs (10.48550/arXiv.<id>), are then fetched from OpenAlex for citation counts, venue, abstract and open-access PDF. OpenAlex single-record lookups are free and need no key. When a preprint and its published version are both found, the more-cited record is shown. For an arXiv paper whose ID is known, the published version is looked up by title.
A found title is accepted only if it occurs whole in the entry, ignoring case, punctuation and hyphenation, or if all its words do, with one missing word allowed for long titles. So "…: A Survey" doesn't match the paper it surveys. Every request times out after 8 s. The open paper is identified from its URL (arXiv, ACL Anthology, DOI), from the arXiv stamp or a DOI on page 1, and by a title from the PDF's metadata or the largest text on page 1. Pointing at a citation for 150 ms starts its lookup. Found papers are cached in chrome.storage.local for a week, and Clear cache on the options page removes them.
Readable URLs and the default viewer. The viewer opens as viewer.html?src=<PDF URL> and then uses history.replaceState to change its address to chrome-extension://<id>/<PDF URL>. When that address is loaded again (reload, history, a copied link), the service worker's fetch handler redirects it to the viewer. If a hard reload bypasses the service worker, a tab listener catches the resulting error page. boot.mjs turns pdf.js's relative resource paths (worker, fonts, CMaps) into absolute ones so they don't follow the changed address. In Always mode, the webRequest listener that recognizes PDFs also sends the tab to the viewer as soon as the response headers arrive, before Chrome's viewer shows the file. Local PDFs are caught when their tab starts loading. The tab remembers the PDF it last opened this way, so going Back to it shows the PDF instead of reopening the viewer.
Node 20+ and Chrome are needed. npm is only used for dev tooling.
npm install
npm test # static checks, matcher, references, native helper and end-to-end tests
npm run package # dist/paper-qa-<version>.zipnpm run checkruns static checks: JS syntax, manifest and package versions match, every referenced file exists, and the vendored viewer is patched.npm run test:matcherruns the matcher stress test (it downloads three arXiv papers). It cuts random passages out of each paper's text layer, distorts them the way model quotes tend to differ (typography changes, extra line breaks, dropped citations,...elisions, a few changed or deleted words, passages crossing a page break), and checks that the highlight lands on the original characters. Current results on ResNet (1512.03385), BERT (1810.04805) and GPT-3 (2005.14165): 1250/1260 passages found. All of the misses are in tables of contents, tables or figure labels, where the text is mostly dot leaders or repeated tokens. Text that doesn't occur in the paper is correctly reported as not found.npm run test:referenceschecks reference parsing and paper IDs with unit cases, then follows every citation link in the three test papers (250 citations). Each one must lead to its whole bibliography entry and nothing more, and must yield a DOI, arXiv ID or title. In ResNet, whose bibliography is numbered, every plain-text[n]citation must lead to the same entry as its link.npm run test:e2eloads the extension into headless Chrome with the Claude API and every paper-lookup API mocked, and checks the whole flow: answering, highlights, quote navigation, zoom, cache restore, PDF and Markdown export, local files, the open-PDF banner, readable URLs (including a reload), "always open" mode, the Implement tab (choosing between two systems, web search and fetch, the prompt download and its cache), the paper info card and citation previews, both linked and plain-text (on a copy of the paper with its links removed), and the Claude Code backend through the real helper, registered in the test profile, with a fakeclaude. SetCHROME_PATHif Chrome isn't in a standard location, andEXTENSION_DIRto test an unzipped package.npm run test:native-hosttalks to the Claude Code helper over the native messaging protocol, withtests/fake-claude.mjsin place of Claude Code: theclaude -parguments and stdin, web search and fetch sources, the login error, a missingclaude, and project launches (with a fake terminal).npm run store-assetsregenerates the icons, store screenshots and promo tiles.
CI (.github/workflows/ci.yml) runs all of this on every push and pull request. It runs the end-to-end test against the built store package and uploads that package as an artifact.
main is protected: changes go through pull requests, which need the Check, test and package CI job to pass before they can be merged. PRs are squash-merged, so the PR title becomes the commit message and must follow Conventional Commits. A check enforces this:
| PR title | Effect on the next release |
|---|---|
fix: … / fix(matcher): … |
patch (1.0.0 → 1.0.1) |
feat: … |
minor (1.0.0 → 1.1.0) |
feat!: …, or a BREAKING CHANGE: footer |
major (1.0.0 → 2.0.0) |
docs:, chore:, ci:, test:, refactor: |
no release on their own |
Releases are automated with release-please:
- After a
feat:orfix:PR is merged, release-please opens (or updates) a PR titled chore: release X.Y.Z. It bumps the version inmanifest.json,package.jsonandpackage-lock.jsonand adds the changes toCHANGELOG.md. - Leave that PR open while more changes land; it keeps itself up to date. When you want to ship, merge it.
- Merging it creates the
vX.Y.Ztag and GitHub release, then runs the Release workflow. That workflow tests the build, attachespaper-qa-X.Y.Z.zipto the release and, if set up, publishes to the Chrome Web Store.
For a one-off manual release, you can still bump the versions yourself and push a vX.Y.Z tag.
The first version has to be submitted by hand:
- Register at the Chrome Web Store Developer Dashboard (one-time $5 fee; the Google account needs 2-step verification).
- Click New item and upload
paper-qa-<version>.zipfrom the GitHub release. - Fill in the Store listing, Privacy and Distribution tabs using
store/LISTING.mdand the images instore/. Then Submit for review.
To let CI publish later versions:
- In Google Cloud, enable the Chrome Web Store API, create an OAuth client (type: Desktop app), and get a refresh token for the scope
https://www.googleapis.com/auth/chromewebstore. Google's Using the Chrome Web Store API guide walks through this. - In the GitHub repository settings, create an environment named
chrome-web-store. Add these secrets:CWS_CLIENT_ID,CWS_CLIENT_SECRET,CWS_REFRESH_TOKENandCWS_PUBLISHER_ID(shown under Publisher > Settings in the dashboard). - Add the repository variables
CWS_EXTENSION_ID(the item's ID) andCWS_PUBLISH=true.
- Scanned PDFs without a text layer don't work. There is nothing to send to Claude and nothing to highlight. The sidebar warns when a PDF has little or no text. Run it through OCR first (for example
ocrmypdf). - Text inside figures, tables and equations is extracted in whatever order the PDF stores it. Quotes from those areas match less reliably, so the prompt steers Claude toward quoting prose.
- In exported PDFs, character positions inside a text span are interpolated from the span's width, so the edges of an exported highlight can be off by a character or two. The in-viewer highlights are exact.
- Using pdf.js's own Find (Ctrl+F) on a highlighted line can temporarily hide that line's Q&A highlight until the page re-renders.
- Reordering or deleting pages with pdf.js's page editor misaligns the highlights. Reload the PDF afterwards.
- Encrypted PDFs can be viewed and questioned, but not exported with annotations.
- Papers longer than the selected model's context window (about 900k tokens for the 1M-token models) are rejected with an error instead of being truncated.
- The Claude Code backend works on macOS and Linux only, and needs the helper installed from a copy of this repository. Each request starts a new Claude Code process, which adds a few seconds, and has no prompt caching between requests.
- The cache lives in
chrome.storage.localon this machine only. Clear it on the options page. - Citation previews need linked citations, which LaTeX papers built with
hyperref(most of arXiv) and many publisher PDFs have. Citations that are plain text, with no link, can't be clicked. - Paper data comes from Semantic Scholar, OpenAlex and Crossref, not Google Scholar, which has no public API. Each card links to a Google Scholar search for the paper. Citation counts differ between these sources; the card says which one it shows.
- A lookup through Crossref and OpenAlex takes about 1–3 seconds (Crossref is sometimes slower), which hovering before the click mostly hides. Cached papers show instantly.
- An extension page can't show another site's address as its own, so the address bar shows
chrome-extension://<id>/followed by the PDF's URL.
Edit the versions at the top of scripts/vendor.sh and run it. Also update pdfjs-dist in package.json to the same pdf.js version. The script downloads pdf.js and pdf-lib, trims files the extension doesn't use (including the PDF-JavaScript sandbox; scripts in PDFs are never run), and patches vendor/pdfjs/web/viewer.html to load the sidebar and allow file: URLs in the viewer's CSP.
MIT. Bundled third-party code keeps its own licenses; see THIRD_PARTY_NOTICES.md. Privacy policy: PRIVACY.md.
