llm-for-zotero: Your Right-Hand Side AI Research Assistant

llm-for-zotero is a plugin for Zotero that integrates Large Language Models directly into the Zotero PDF reader. Unlike tools that require uploading PDFs to a web portal, this plugin lets you chat with your papers without leaving Zotero. It sits quietly in the reader sidebar — your standby research assistant, ready whenever you need it.

Documentation:

• English
• Chinese

• Skills — Customizable guidance files that shape how the agent handles different tasks. 8 built-in skills included, plus a portal for creating your own. See Skills.
• Standalone Window Mode — Open the LLM Assistant in its own dedicated window, separate from the Zotero reader sidebar. See Standalone Window Mode.
• File-Based Notes — Save research notes as Markdown files in any local directory — works with Obsidian, Logseq, or any plain markdown folder. See File-Based Notes.
• Agent Mode (beta) — LLM-for-Zotero can now act as an autonomous agent inside your Zotero library. See Agent Mode for details.
• Codex auth — ChatGPT Plus subscribers can use their Codex quota to access Codex models (e.g. gpt-5.4) without an API key. See Codex Auth Setup.
• MinerU PDF parsing — High-fidelity PDF extraction that preserves tables, equations, and figures. See MinerU PDF Parsing.

• Installation
• Configuration
• Usage Guide
• Features
• File-Based Notes
• Agent Mode (beta)
• Skills
• WebChat Setup
• Codex Auth Setup
• MinerU PDF Parsing
• Roadmap
• FAQ
• Contributing
• Star History

Download the latest .xpi file from the Releases Page.

Open Zotero → Tools → Add-ons → click the gear icon → Install Add-on From File → select the .xpi file.

Restart Zotero to complete the installation. The plugin will automatically check for future updates when Zotero starts.

Open Preferences → navigate to the llm-for-zotero tab.

1. Select your Provider (e.g. OpenAI, Gemini, Deepseek).
2. Paste your API Base URL, secret key, and model name.
3. Click Test Connection to verify.

The plugin natively supports multiple provider protocols: responses_api, openai_chat_compat, anthropic_messages, gemini_native, and more.

You can also set up multiple providers, each with multiple models for different tasks (e.g. a multimodal model for figures, a text model for summaries). Cross-check answers across models for more comprehensive understanding.

You can set different reasoning levels per model in the conversation panel (e.g. "default", "low", "medium", "high", "xhigh") depending on model support. Power users can also adjust hyperparameters like temperature, max_tokens_output, etc. for more creative or deterministic responses.

1. Open any PDF in the Zotero reader.
2. Click the LLM Assistant icon in the right-hand toolbar to open the sidebar.
3. Type a question such as "What is the main conclusion of this paper?"

On the first message, the model loads the full paper content as context. Follow-up questions use focused retrieval from the same paper, so the conversation stays fast and relevant.

When you ask a question, the model generates answers grounded in the paper's content. Click any citation to jump straight to the source passage in your Zotero library.

Get a concise summary of any paper in seconds. The summary is generated from the full text of the open PDF, and you can customize the prompt (e.g. focus on methodology, results, or implications).

Select any complex paragraph or technical term and ask the model to explain it. You can add up to 5 pieces of context from the model's answer or the paper to refine the explanation.

An optional pop-up lets you add selected text to the chat with one click. Don't like it? Disable it in settings — your choice.

Take a screenshot of any figure and ask the model to interpret it. Supports up to 10 screenshots at a time.

Open multiple papers in different tabs and compare them side by side. Type / to cite another paper as additional context.

Upload documents from your local drive as additional context — supports PDF, DOCX, PPTX, TXT, and Markdown files. (Feature by @jianghao-zhang.)

Save any answer or selected text to your Zotero notes with one click — seamless integration with your note-taking workflow.

Local conversation history is automatically saved and associated with the paper you're reading. Export entire conversations to Zotero notes in Markdown format — including selected text, screenshots, and properly rendered math equations.

Customize quick-action presets to match your research workflow — predefined prompts available at the tap of a button.

Open the LLM Assistant in its own dedicated window, separate from the Zotero reader sidebar. The standalone window gives you a full-sized chat interface with a collapsible conversation history panel on the left.

• Keyboard shortcut: Ctrl+Shift+L (macOS: Cmd+Shift+L)
• Paper chat & Library chat: Switch between paper-specific and library-wide conversations using the tabs at the top.
• Conversation history: Browse past conversations organized by date (Today, Yesterday, Last 7/30 days, Older) in the left sidebar.
• All features available: Everything you can do in the reader sidebar — screenshots, file uploads, agent mode, quick-action presets — works identically in the standalone window.

While the standalone window is open, the reader sidebar panels display a placeholder with options to focus the window or close it and return to the sidebar.

Beyond Zotero's built-in notes, the agent can save research notes as Markdown files in any local directory you choose. The plugin is not tied to any specific note-taking app — point it at an Obsidian vault, a Logseq graph, or a plain folder of .md files, and the agent will write notes there with full metadata, citations, and optionally extracted figures.

Open Preferences → llm-for-zotero and scroll to the Notes Directory section.

Click Test Write Access to verify the plugin can write to your directory.

Ask the agent to write a note using the nickname you configured — e.g. "Summarize this paper and save it to Obsidian" or "Log this to my Logseq". The agent will:

1. Gather content from the paper (metadata, summary, key points, figures, etc.).
2. Compose a Markdown note following the conventions of the write-note skill.
3. Add YAML frontmatter that matches the write-note template (title, created, tags, citekey, doi, journal); author information is kept in the note body, not frontmatter.
4. Optionally copy figures from MinerU-parsed PDFs into the attachments folder.
5. Write the note to {notes_directory}/{default_folder}/{title}.md.

Notes use Pandoc citation syntax ([@citekey]), compatible with Obsidian's Zotero Integration and Pandoc plugins, as well as most other Markdown readers.

Customizing the note format: Note templates and figure-embedding rules live in the write-note skill, not in preferences. Open the Standalone Window → Skills portal to edit it — see the Skills section for details.

Agent Mode is disabled by default. Enable it in Preferences, then toggle Agent (beta) in the context bar.

When enabled, the LLM becomes an autonomous agent that can read, search, and write within your Zotero library.

The agent ships with focused tools split into read (no confirmation needed) and write (route through a confirmation card with batched undo).

The design philosophy is read tools are unrestricted; write tools always confirm and stay undoable. Ask the agent what it can do — it will tell you.

This is the first step for Agent Mode. The goal is a versatile agent that masters all tasks in your Zotero library.

Skills are customizable guidance files that shape how the agent approaches different types of requests. When your message matches a skill's trigger patterns, the skill's instructions are automatically injected into the agent's prompt — guiding it to use the most efficient tools and workflows for the task.

Skills require Agent Mode to be enabled. They have no effect in standard chat mode.

The plugin ships with 8 built-in skills covering common research workflows:

1. Open the Standalone Window and click the Skills icon in the toolbar.
2. Click "+ New skill" to create a template.
3. Edit the id, regex match patterns, and instruction body in your text editor.
4. Save — the skill loads immediately, no restart needed.

Skills are stored as Markdown files in {ZoteroDataDir}/llm-for-zotero/skills/. Left-click any skill to edit it; right-click for Show in file system or Delete.

WebChat mode lets you send questions directly to chatgpt.com through a browser extension — no API key needed. Your queries are relayed from Zotero to the ChatGPT web interface, and responses are streamed back into the plugin.

• A ChatGPT account (Free, Plus, or Team)
• A Chromium-based browser (Chrome, Edge, Brave, Arc, etc.)

1. Download the browser extension:

   • Go to github.com/yilewang/sync-for-zotero → Releases
   • Download the latest extension.zip
   • Unzip the file to a folder on your computer

2. Install the extension (sideload):

   • Open your browser and navigate to chrome://extensions
   • Enable Developer Mode (toggle in the top-right corner)
   • Click Load unpacked and select the unzipped extension folder
   • The "Sync for Zotero" extension should now appear in your extensions list

3. Configure the plugin:

   • Open Zotero → Preferences → llm-for-zotero
   • Set Auth Mode → WebChat
   • The model is automatically set to chatgpt.com

4. Start chatting:

   • Open a ChatGPT tab in your browser (keep it open while using WebChat)
   • Open a paper in Zotero — the plugin panel shows the "chatgpt.com" indicator with a connection dot
   • A green dot means connected; red means the extension or ChatGPT tab is not detected
   • Type a question and send — the plugin relays it to ChatGPT and streams the response back

• PDF attachment: Right-click the paper chip to toggle PDF sending (purple = send, grey = skip)
• Screenshots: Use the camera button to attach figure screenshots to your message
• Conversation history: Click the clock icon to browse and load past ChatGPT conversations
• Exit: Click the "Exit" button to return to regular API mode

If you have a ChatGPT Plus subscription, you can use Codex auth to access Codex models (e.g. gpt-5.4) without an API key. The plugin reuses your ChatGPT login via the Codex CLI — a great way to save on token costs.

Special thanks to @jianghao-zhang for contributions to this feature.

1. Install the Codex CLI (one-time):

   • macOS: Install Node.js 18+ or brew install node, then:

     npm install -g @openai/codex

   • macOS (Homebrew alternative): brew install --cask codex (no Node.js needed).
   • Windows/Linux: Install Node.js 18+, then npm install -g @openai/codex.

2. Log in with your ChatGPT account:

   codex login

   A browser window opens — sign in with your ChatGPT Plus account. Credentials are saved to ~/.codex/auth.json.

3. Configure the plugin (Zotero → Preferences → llm-for-zotero):

   • Auth Mode → codex auth
   • API URL → https://chatgpt.com/backend-api/codex/responses
   • Model → a Codex model (e.g. gpt-5.4)
   • Click Test Connection to verify.

• Reads local credentials from ~/.codex/auth.json (or $CODEX_HOME/auth.json).
• Automatically attempts token refresh on 401 responses.
• Embeddings are not supported in codex auth mode yet.
• Local PDF/reference text grounding and screenshot/image inputs are supported.
• The Responses /files upload + file_id attachment flow is not supported yet.

MinerU is an advanced PDF parsing engine that extracts high-fidelity Markdown from PDFs — preserving tables, equations, figures, and complex layouts that standard text extraction often mangles. When enabled, the plugin sends your PDF to the MinerU API for parsing and caches the result locally. All subsequent interactions with that paper use the MinerU-parsed content, giving the LLM much richer and more accurate context.

1. Open Zotero → Preferences → llm-for-zotero tab.
2. Find the MinerU section and check Enable MinerU.
3. (Optional) Enter your own MinerU API key — see below.
4. Open any PDF and start chatting. The plugin will automatically parse the PDF with MinerU on first use and cache the result for future conversations.

The plugin provides a shared community proxy so MinerU works out of the box without an API key. However, the shared quota is limited. For heavier usage, you can apply for your own key:

1. Go to mineru.net and create an account.
2. Navigate to your account settings and generate an API key.
3. In Zotero → Preferences → llm-for-zotero → MinerU section, paste your API key.
4. Click Test Connection to verify.

When a personal API key is provided, the plugin calls the MinerU API directly (https://mineru.net/api/v4). Without a key, it uses the community proxy.

• Agent mode (beta)
• MinerU PDF parsing
• GitHub Copilot auth
• WebChat mode (ChatGPT web sync)
• Standalone window mode (#78)
• File-based notes (Obsidian, Logseq, any Markdown directory)
• Local MinerU support
• Customized skills
• Cross-device synchronization

Q: Is it free to use?

Yes, absolutely free. You only pay for API calls if you choose a paid provider. With Codex auth, ChatGPT Plus subscribers can use Codex models without a separate API key. If you find this helpful, consider leaving a ⭐ on GitHub or buying me a coffee.

Q: Does it work with local models?

Yes — as long as the local model provides an OpenAI-compatible HTTP API, you can connect it by entering the appropriate API Base URL and key in settings.

Q: Is my data used to train models?

No. You use your own API key, so data privacy is governed by the terms of your chosen provider (e.g. OpenAI's API terms typically exclude training on API data).

Q: How do I report a bug or ask a question?

Please open an issue on GitHub. I'll do my best to help!

Contributions are welcome! Whether it's bug reports, feature requests, or pull requests — feel free to open an issue or submit a PR.