Paper Pilot for Zotero 7-10

Languages: English | 한국어 | 简体中文 | 繁體中文

Paper Pilot turns the Zotero 7-10 PDF reader into an AI-assisted paper workbench.

Paper Pilot is an AI reading workbench for the Zotero 7-10 PDF reader. It adds a paper-scoped chat pane, structured paper tools, agent-led verified research discovery, and local CLI-based AI execution directly inside Zotero.

Research Studio

A project's Open Studio window (Research Studio) adds local original-format documents, a DOCX editor, Markdown/source editing, data tables and executable notebooks. The project assistant captures selected file revisions and presents changes for individual review. It offers Codex/Claude CLIs and a loopback model endpoint; network inference is explicit and API keys stay in the open window. Notebook execution requires a Python environment with jupyter-client and ipykernel (and IRkernel for R), configured in Paper Pilot settings. Code runs with your local account permissions only when you choose Run.

These capabilities are implemented in source. Verification remains specific to the build, provider and format; browser checks do not replace native Zotero or Word round trips. See the full scope and verification contract and runtime checklist.

Local compilation uses installed Tectonic (.tex), Typst (.typ), or MyST plus Typst (Markdown). Configure executable paths in settings. Missing packages/templates may require downloads. Local project bundles include document versions, conversations and historical research snapshots; restore into a new project and explicitly reconnect Zotero sources. Zotero attachment bytes and runtime environments are separate. DOCX supports Word citation fields with explicit CSL refresh; Word uses its own formatting engine when refreshing. Cloud collaboration and synchronization are deferred.

Studio also provides Word footnotes/endnotes, contents/caption fields, editable AI proposals, notebook output provenance, and a project links view. Supported literal paths are repaired atomically on rename; dynamic code paths are not inferred. Output inspection flags changes to the recorded cell/output or captured inputs. Zotero reference snapshots can open currently verified supporting passages through Research Workspace.

Open a DOCX (or a saved journal template), choose Assistant → Draft paper, select source files, and enter the topic, article type and journal requirements before sending. The connected provider proposes a manuscript for review; applying it appends styled title/section/body paragraphs and saves a new version. Existing content is preserved. Missing evidence and citations remain explicit placeholders; use References for live citation fields. See academic drafting. Manuscripts default to academic English, independently of the request/source language; assistant explanations follow your language. Explicit requests can select another manuscript language.

New document groups formats by purpose and offers Blank, built-in or saved templates with a filename preview. The assistant keeps provider/model controls visible, resumes conversations from History, and shows removable context-file chips above the composer.

Chat workflow

Use Focus chat to temporarily hide supporting panels. Draft the next question while a response runs, inspect/remove attached selection context, choose short/default/detailed answers, and open / Actions for Explain, Summarize, Translate and Critique. Search current or saved conversations for the current paper; jumping to a result can reveal messages outside the visible history window.

A submitted question keeps its exact PDF source and execution settings. Retry adds an attempt to that question; More offers editing in a separate conversation, branching from an answer, pinning context, a previewed Zotero note, and a comparison question for a chosen project. PDF citation buttons use local quote matching and recheck the source before navigation. A matched location is not a guarantee that the claim is true.

Project inboxes can retain discovery candidates before a PDF is available. Link the intended existing item/PDF explicitly, then manage screening, reading progress and understanding separately. Saved project members can be used without repeating the library selection.

Drafts are memory-only. Full/prompts-only/off history rules also apply to new chat metadata; assistant-derived summaries and pins are excluded from prompts-only continuity. PaperPilot's history setting does not erase external CLI history. Provider availability depends on the installed CLI and account; failures are reported instead of silently using another provider. See the architecture, evaluation, and runtime checklist.

At a glance

• AI chat directly inside the Zotero Reader
• Two local engine modes: Codex CLI and Claude Code
• Structured paper workbench for brief, compare, contributions, limitations, and follow-ups
• Structured PDF workspace extraction via OpenDataLoader PDF
• Zero-configuration verified prior-work discovery with official publication evidence and three evidence lanes
• Critical Read — a reader-first, seven-step paper evaluation workflow with a final report
• Auto-highlight plus persisted paper-scoped session history
• Paper Mastery — multi-round Socratic comprehension check with a final Markdown learning report
• Automated verification and focused Zotero 9 and 10 reader-pane, discovery, and Critical Read runtime smokes are recorded; the Research Workspace project window and broader Zotero 7-10 cross-engine matrix remain manual QA

Integrated Research Workspace

Research Workspace is built into Paper Pilot and uses the same selected local engine, paper extraction, and run lifecycle. A persistent modeless project window stays available with zero, one, or multiple selected items and provides screening, claim–evidence ledgers, comparisons, audits, mastery, citation workflows, citation/reference health, contradiction/gap review, scoped export, a local Living Review change inbox, and five editable Research project templates. Template presets only highlight recommended capabilities; they never start analysis or hide other capabilities, and exports retain the immutable template snapshot plus current assumptions. Citation & Reference Health derives a local checklist from current saved citation, methodology, and reproducibility artifacts, local Zotero correction/retraction metadata signals, and an optional bounded draft excerpt; it never produces an aggregate truth score. Living Review checks Zotero attachment and annotation metadata without reading their text or calling a model or network service. Safe Zotero collection/tag sync offers a complete preview and preview-bound approval token for one-way additions to existing collections and existing tags, writes a separate revisioned receipt before the transaction, fails closed without Zotero transaction support, and can undo only receipt-owned additions. It never creates or deletes Zotero items, collections, or tags and never writes bibliographic fields, PDFs, notes, attachments, or annotations. Open it from Tools → Open Research Workspace…, the library item context menu, or the Research Workspace button in the Workbench. Leaving a project or closing the window while an analysis runs asks before cancelling it. A partial run reports its failed papers and offers Resume, and archived projects can be opened and restored. Install only the Paper Pilot XPI; there is no companion add-on or Research Monitor.

Use Delete project… on an active or archived project card, or in Settings, to permanently remove the project and its Studio documents, versions, conversations, artifacts, managed exports, and owned runtime/temporary files. Paper Pilot waits for in-flight work and confirmed process shutdown before removing files; cancelling a dirty Studio window stops deletion. Failed cleanup remains retryable from the project list. Original Zotero items/attachments, separately saved files, and shared caches remain. Older flat exports or temporary workspaces without project ownership records cannot be safely attributed and are preserved.

Getting started

1. In the Zotero library, select up to 12 papers that have PDFs. Right-click them and choose Open Research Workspace….
2. Under Selected in Zotero, choose Create project with N papers, or add the papers to an existing project. Paper Pilot reads the PDFs on your computer at this step; no model runs yet.
3. The project opens on its Analyze tab with the analysis tools ready. Compare the papers, build an Evidence Matrix, synthesize an answer, or audit one paper. Each result is saved under Results.
4. Papers holds reading progress and screening, Checks holds contradiction, citation-health, and Living Review checks, and Settings holds the project details, export, and Zotero sync.
5. Choose Open Studio to write up the project in Research Studio: drafts, citations from the project's Zotero papers, notebooks, and the project assistant.

Screenshots and demo

Studio screenshots show the assistant and New document dialog in Chrome with synthetic project data (2026-10-24). Native Zotero visual and keyboard checks remain separate. Use the capture guide when adding or refreshing screenshots.

Status

Paper Pilot is under active development.

What is already in place:

• automated local test coverage for core logic
• production build generation for the Zotero add-on
• reader-pane workflows for chat, paper tools, recommendations, and highlighting

What is still required before calling it fully production-ready:

• end-to-end manual QA inside real Zotero 7-10 runtimes
• broader install and environment validation across real user setups

See docs/manual-qa.md for the current runtime checklist.

What the plugin does

1. Reader-side AI chat

• Adds an AI pane to the Zotero reader/item pane
• Keeps conversations scoped to the active paper
• Supports per-paper engine switching between Codex CLI and Claude Code
• Preserves follow-up continuity within the same paper/session
• Supports Past sessions for reopening, renaming, deleting, and clearing saved sessions for the current paper
• Uses New session to preserve the current session and start a blank draft for the same paper; it asks first when Critical Read or Paper Mastery has progress that the current history setting would not keep

2. Paper-aware actions from the reader

From PDF selections or annotations, the plugin can seed AI workflows such as:

• Ask AI
• Explain
• Summarize
• Translate

Select a word or short phrase in a PDF and click Naver Dictionary. A separate, modeless Zotero dictionary window shows the matching headword, pronunciation symbols, up to three meanings, and the dictionary source. Inflected words can show their dictionary headword. Keep reading the PDF while the window is open; another lookup updates the same window. Close with Esc or Close dictionary. More on Naver opens the source only when clicked. This online lookup sends only the selected query, starts no AI run, and does not save results to Paper Pilot history. The button accepts up to 80 characters and 8 words. It uses Naver's internal search response, which may change; failures and missing matches are shown in place with a retry option for failures.

To explain a figure or table, click Explain figure or table (the dashed-frame chart icon) in the PDF reader toolbar, then drag a box around the figure. Paper Pilot switches Zotero to its Select Area tool for that one selection. When you release the mouse, a separate, modeless Paper Pilot window opens beside the PDF and explains the area: what it shows, how to read it, key points, its role in the paper, and caveats. Each key point is labeled Visible (read from the image), Paper (stated in the paper), or Inference. The reader then returns to its previous tool. While the mode is on, a short notice over the PDF says what to do. Click the button again or press Esc to cancel; the mode also ends by itself after two minutes, and the notice says so. To explain an existing area annotation, click Explain on its card in the left sidebar, or right-click it and choose Explain figure or table. The run uses the paper's engine in read-only analysis mode. Codex CLI receives the image as an attachment; Claude Code opens a copy in its workspace. When Zotero has no cached image of the area, the explanation uses only the caption and page text and says so. Stop or closing the window ends the run. Results stay in memory for the current Zotero session and are not saved to history or notes. The area annotation stays in Zotero; delete it as usual if you do not need it.

3. Paper workbench tools

The reader pane includes structured paper workflows for the active paper:

• Research brief
• Compare
• Contributions
• Limitations
• Follow-ups
• Save latest to note
• Save for collection
• Clear cards

These workflows are designed to produce compact, reader-pane-safe outputs rather than long generic chat responses.

4. Agent-led verified research discovery

Choose Find verified prior work and optionally describe a research concern. Discovery needs Codex CLI with Allow web search when needed turned on; with any other setup, the entry points stay disabled and show the reason. The active agent infers the relevant fields, adjacent fields, leading venues, and query families; the user never has to maintain a conference list. Results are separated into:

• Verified main-conference papers — high-confidence, paper-level official evidence for an observed main track at a leading venue
• Other peer-reviewed work — journals, workshops, Findings, other tracks, or published records whose main-track status is not established
• Frontier / novelty radar — recent preprints and submissions useful for checking current direction or possible idea overlap

Paper Pilot searches standardized scholarly sources, stages reproducible discovery artifacts for the local agent, and live-checks qualifying official evidence. The venue model is open-world: ACL, EMNLP, CVPR, NeurIPS, ICLR, ISCA, MICRO, HPCA, ASPLOS, USENIX venues, and relevant venues in other fields are judged from evidence rather than selected from a fixed allowlist. You can open official evidence or public reviews, request a review insight, add a paper to a collection with its evidence metadata, and save the complete three-lane result to a Zotero note.

Critical Read

Critical Read guides the reader through seven ordered steps: scan the abstract/figures/tables, identify the research question, investigate prior work, evaluate methodology, form an independent results-based conclusion, compare it with the authors' conclusion, and test alternative explanations. Reader input is required before agent analysis at the independent-judgment steps. Revising an earlier step invalidates dependent later work, and the final report keeps reader observations, paper claims, agent inference, and external discovery evidence visibly separate.

5. Auto-highlight workflow

The plugin includes an auto-highlight path for extracting high-confidence passages from the active paper and surfacing key passages back in the reader workflow.

6. Paper Mastery (comprehension check)

The reader pane includes a Paper Mastery workflow that drives a multi-round Socratic comprehension check on the active paper:

• The AI generates one open-ended question at a time, scoped to the paper's core contributions, methodology, or assumptions.
• The reader answers in free text; the AI evaluates each answer and records whether a topic was understood. Press Ctrl+Enter (Cmd+Enter on macOS) to submit. An unsent answer is kept if the pane redraws.
• After grading, your answer, the feedback, and an explanation for a missed topic stay on screen while the next question is prepared. Click Next question when you are ready to continue.
• When the session ends, a Markdown learning report summarizes strengths, areas for improvement, key misconceptions, and recommended re-reading.

Mastery prompts request strict JSON for questions and evaluations. Reader answers and prior rounds are serialized as untrusted JSON source data. The parser validates fields and bounds, handles strings/escapes, and can recover a fenced JSON response.

7. Local workspace artifacts for CLI engines

When you ask a question in Codex CLI or Claude Code mode, Paper Pilot writes a per-paper workspace so the CLI can inspect local paper context before answering.

Artifacts written for every engine:

• paper.md
• paper.json
• paper.txt
• selection.json
• conversation-context.md (chat runs)
• metadata.json
• annotations.json

All engines additionally write CONTEXT_INDEX.md (a reading-order file map). Discovery runs stage discovery-request.json, discovery-plan.json, discovery-candidates.json, and discovery-evidence.json; Codex CLI also creates a figures/ directory.

paper.md is the structured Markdown view, paper.json carries structured PDF elements plus extraction metadata, and paper.txt remains as the compatibility/plain-text fallback. When Java is unavailable, Paper Pilot records the fallback in metadata.json.

This keeps the selected CLI grounded in the current paper, selection context, and recent conversation history. When Java 11+ is available, paper.md and paper.json come from the bundled OpenDataLoader runtime. If structured extraction is unavailable, Paper Pilot falls back to Zotero attachmentText and records that in metadata.json.

Feature overview

Area	Current support
Reader chat	Paper-scoped AI chat inside Zotero Reader
Engines	Codex CLI and Claude Code
Paper workbench	Research brief, compare, contributions, limitations, follow-ups
Discovery	Agent-inferred fields/venues, official publication verification, three evidence lanes, public review insight
Critical reading	Seven reader-first steps, dependency invalidation, source-aware final report
Persistence	Save latest output to note, save workbench artifacts for collections
Context grounding	Workspace artifacts, OpenDataLoader-backed structured PDF context, retrieval context, recent-turn continuity
Highlighting	Auto-highlight workflow for key passages
Comprehension	Paper Mastery multi-round comprehension check with Markdown learning report

Engine modes

Mode	Best for	Current strengths
Codex CLI	workspace-aware paper analysis	local workspace artifacts, resumable runs, model/sandbox/approval controls, optional web search
Claude Code	workspace-aware paper Q&A	local workspace artifacts, model/effort/permission controls, paper-scoped continuity

Codex CLI mode

Codex mode is the more workspace-oriented path. The current codebase includes support for:

• executable discovery and validation
• login/status checks
• workspace writability checks
• model selection across the bundled Codex model catalog (gpt-6-astra default, plus gpt-6-sol, gpt-6-luna, gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna), with a reasoning effort picker next to the model picker that lists only the levels the chosen model supports (up to max/ultra where supported)
• sandbox and approval settings
• optional web-search toggle
• resumable follow-up runs tied to the current paper

Claude Code mode

Claude Code mode uses the local claude CLI in print mode with the same paper workspace artifacts used by the reader chat and workbench flows. The current codebase includes support for:

• configurable executable path
• model selection across the Claude Code CLI family aliases (sonnet default, plus opus, haiku, and fable), which the installed CLI resolves to the model available for each alias, plus pinned ids claude-opus-5-5, claude-sonnet-5-5, claude-haiku-5-5, claude-fable-5-1, claude-opus-5, and claude-sonnet-5
• any other model id typed in settings (for example claude-opus-5-5[1m] or a Bedrock/Vertex model id) is passed to the CLI unchanged; hand-typed names such as Opus 5.5 or claude-opus-5.5 are normalized to claude-opus-5-5, keeping a context suffix such as [1m]
• optional effort level (low, medium, high, xhigh, or max), set in settings or next to the model picker. Saving the model and effort in the engine popover closes the popover. The empty choice keeps the CLI default: settings call it Claude Code default, and the picker calls it default effort. The level is passed as --effort only when the installed CLI's --help lists that flag
• configurable permission mode for chat runs
• paper-scoped follow-up continuity
• retrieval/context assembly for the active paper

How Paper Pilot shapes AI output

Several reader-pane workflows expect structured outputs instead of free-form chat.

Current prompt surfaces include:

• Research brief
• Agent-led verified research discovery
• Public review insight
• Critical Read
• Paper tools
• Paper compare
• Auto-highlight
• Paper Mastery (comprehension check)
• Workspace/chat prompt assembly

Across these surfaces, Paper Pilot prompts the model to prefer full current-paper workspace content when available. Metadata and abstracts are orientation or fallback context; if an answer depends on abstract-only context, the output should say so when that limitation affects confidence. Prompts also ask models to keep paper claims, reader-relevant interpretation, and outside/web findings separate, with section, page, figure, or table support when available.

See docs/prompt-contracts.md for the exact output-shape intent and guardrails.

Requirements

• Zotero 7, 8, 9, or 10
• Node.js 22.18+ for development
• npm for dependency and build workflows
• Java 11+ for OpenDataLoader structured PDF extraction; optional when using the attachment-text fallback
• For reader and Research Workspace AI, at least one authenticated local CLI:
  • Codex CLI, or
  • Claude Code

Reader and Research Workspace AI require an authenticated local CLI. Studio editing works without one; Studio AI can instead use a compatible loopback model. Java enables structured extraction; attachment text remains the fallback.

Development quick start

Install dependencies:

npm install

Run tests:

npm test

Build the add-on:

npm run build

OpenDataLoader packaging note:

• npm run build copies the OpenDataLoader JAR into addon/chrome/content/vendor/opendataloader/ before the xpi is packed
• the built add-on bundles that JAR, but still requires a local Java runtime to execute it

npm start, npm run build, and npm run release vendor the OpenDataLoader runtime JAR into the add-on automatically via scripts/prepare-opendataloader.mjs.

Local CLI runs require a Unix environment with /bin/zsh and standard process tools. Native Windows runs are not supported. Use bash scripts/doctor.sh . to check the login-shell CLI paths, versions, and available authentication status; pass your Zotero profile directory as a second argument to compare its extraction runtime with the bundle. Research Workspace artifacts record the admitted CLI model, reasoning level, and response language. Source changes invalidate results, and resumed units require matching source, context projection, and execution settings. Codex's allowed-model preference restricts both the picker and the effective model; an obsolete-only list falls back to the current catalog.

Creating a GitHub release

Release publishing is tag-driven. Keep the package version and the tag aligned:

1. Update package.json and package-lock.json to the release version on main.
2. Merge that version bump to main.
3. Create and push the matching tag, for example git tag "v<version>" && git push origin "v<version>".
4. The Release workflow now runs scripts/check-release-tag-version.mjs before publishing. It fails fast if the ref name does not exactly match v${package.json.version}.

If you use workflow_dispatch, run it from the matching release tag ref. Branch refs are rejected by the same guard.

Build output

A successful build generates the Zotero add-on package in build/.

Typical outputs include:

• build/paper-pilot.xpi
• build/update.json
• build/update-beta.json

Install in Zotero

1. Build the project with npm run build.
2. Open Zotero.
3. Install the generated .xpi through Zotero's add-on installation flow.
4. Restart Zotero if required.
5. Open a PDF attachment and confirm the Paper Pilot reader pane appears.
6. Ask a paper question and inspect the newest workspace to confirm paper.md, paper.json, and paper.txt were written together.
7. Check metadata.json and confirm extractionMethod is opendataloader-pdf when Java is available, or zotero-attachment-text when fallback was used.

First-run checklist

After installing the .xpi, this is the fastest way to validate the plugin:

1. Open Zotero settings and configure a local Codex CLI or Claude Code executable path.
2. Open a PDF attachment in Zotero Reader.
3. Open the Paper Pilot pane.
4. Select Codex CLI or Claude Code.
5. Ask a question about the current paper.
6. Try one structured workbench action such as Research brief or Compare.

Configuration notes

The preferences UI currently exposes settings across these areas:

• General
• Claude Code
• Codex CLI
• Workspace (workspace root and auto-clean, shared by both engines)
• Retrieval (chunk size, overlap, and top-k sit in a collapsed Advanced retrieval group)
• Privacy (one Session history choice: Save prompts and responses, Save prompts only, or Do not save session history)
• Research Studio (local compiler paths and Python kernel environment)

Important current details:

• most controls use English labels; Critical Read guidance, step titles and report labels follow the response-language preference
• response language is normalized to English, Korean, or Chinese
• Korean answers use natural Korean sentences while retaining English technical terms from the paper or question by default; request a Korean term explicitly when needed
• response language applies to new reader answers and artifacts plus Critical Read presentation copy; saved prose is not translated, and Studio academic manuscripts default to English unless explicitly requested otherwise
• runtime code already reads many engine, retrieval, workspace, and privacy preferences
• structured PDF extraction uses a bundled OpenDataLoader JAR and falls back to Zotero attachmentText if Java/runtime extraction is unavailable
• full real-runtime QA of every preference path is still part of the remaining manual verification work

Typical usage flow

1. Open a PDF in Zotero Reader.
2. Open the Paper Pilot pane.
3. Choose Codex CLI or Claude Code.
4. Ask a question about the paper.
5. Optionally use a selection or annotation action to seed the next prompt.
6. Use the workbench buttons for structured outputs such as brief, compare, contributions, or follow-ups.
7. Save useful outputs to a note or collection-linked artifact when needed.

Project structure

addon/      Zotero add-on manifest, locales, preferences UI, static assets
src/        TypeScript source for reader UI, engine integrations, context, tools, and workflows
test/       Node-based regression tests for prompt builders, parsing, storage, and workflow logic
docs/       Manual QA checklist, prompt contracts, and supporting product notes
scripts/    Build/release CLI, OpenDataLoader preparation, release-tag guard, and environment doctor
build/      Generated add-on artifacts

Key source areas:

• src/modules/readerPane.ts — main reader pane UI and workflow wiring
• src/modules/codex/ — Codex CLI execution, status, parsing, and command building
• src/modules/claude/ — Claude Code execution flow
• src/modules/context/ — paper context retrieval and workspace artifact generation
• src/modules/researchWorkspace/ — project intake, evidence, multi-paper analysis and persistence
• src/modules/studio/ — project documents, assistant, notebooks, compilers, references and bundles
• src/modules/autoHighlight/ — highlight extraction workflow
• src/modules/paperTools.ts — structured contribution/limitation/follow-up prompts
• src/modules/researchBrief.ts — compact per-paper brief generation
• src/modules/discovery/ — agent-led search planning, provider retrieval, evidence verification, parsing, and ranking
• src/modules/relatedRecommendations.ts — verified-discovery workflow and Zotero collection integration
• src/modules/criticalRead/ — seven-step reader-first analysis and report workflow
• src/modules/paperCompare.ts — bounded multi-paper comparison flow

Verification

The repository currently includes automated checks for core logic such as:

• engine mode selection
• Codex command building and shell behavior
• workspace artifact generation, including paper.md / paper.json
• research brief parsing
• paper-tool parsing
• related-paper recommendation parsing
• compare and artifact-save flows
• auto-highlight parsing/matching
• discovery, Critical Read, session persistence, and Research Workspace contracts

Core commands used during local verification:

npm test
npm run build

Manual runtime verification is still required in Zotero itself. Use docs/manual-qa.md.

Known limitations

• The project is not yet claiming full production readiness.
• Focused Zotero 9 and 10 reader-pane, discovery, and Critical Read runtime QA is recorded in docs/manual-qa.md; the Research Workspace project window and broader compatibility and cross-engine matrix remain manual QA.

Roadmap

Near-term priorities that are already reflected by the current repo state:

• complete real Zotero runtime QA using docs/manual-qa.md
• add screenshots and short demo assets under docs/images/
• broaden install and environment verification across more real setups
• keep documentation aligned with the evolving reader-pane workflows

Contributing

Contributions are welcome.

For setup, workflow expectations, and documentation guidance, see CONTRIBUTING.md.

License

This project is licensed under AGPL-3.0-or-later.

Additional docs

• docs/images/README.md
• CONTRIBUTING.md
• docs/manual-qa.md
• docs/architecture.md
• docs/prompt-contracts.md
• docs/research-studio-spec.md
• docs/academic-drafting.md
• docs/chat-context-evaluation.md