• Home
• /
• llm-for-zotero Documentation
• Edit on GitHub ↗

llm-for-zotero: A Research Agent System for your Zotero Library

📖 中文版使用手册

llm-for-zotero brings Large Language Models into the Zotero reader, so you can ask questions, summarize papers, inspect figures, compare sources, and save notes without leaving your library. It works with standard API providers, local OpenAI-compatible models, WebChat, Codex App Server, and Claude Code.

Demo Video

Watch how to conduct a literature review in Library chat with the llm-for-zotero agent.

Quick Start

1. Download the latest .xpi file from the Releases page.
2. In Zotero, open Tools → Add-ons → gear icon → Install Add-on From File, then select the .xpi.
3. Restart Zotero.
4. Open Preferences → llm-for-zotero, choose a provider, enter the base URL, key, and model, then click Test Connection.
5. Open a PDF in Zotero and click the LLM Assistant icon in the right-hand toolbar.

If you do not want to use a provider API key, start with WebChat or Codex App Server.

Requirements

• Zotero
• A model backend: provider API key, local OpenAI-compatible model, WebChat, Codex App Server, or Claude Code.
• A Chromium-based browser for WebChat mode.
• Node.js 18+ for npm-based Codex CLI installation and for Claude Code mode. The macOS Codex cask does not require a separate Node.js install.
• For general web search in Agent Mode: a Tavily key, an official DeepSeek model profile, or AnySearch (no key needed).
• A personal MinerU API key or a local mineru-api server is recommended if you enable MinerU parsing.

Choose Your Setup

What’s New

v3.9.14

• Task progress shows the sources of each answer. The side panel lists, for each question, the papers and web pages the Agent used and the passages it read. Show in answer jumps to the sentence that cites a source. See Task Progress and Sources.
• Web answers credit their sources with numbered marks and a source chip, which stay when you copy the answer.
• Conversations grouped by agent: the window sidebar can group chats into Agent, Codex, and Claude sections.
• The composer floats over the bottom of the chat and grows as you type.
• MinerU local server on demand: the plugin can start a local MinerU server when it parses a PDF and stop it when it is idle. See Using a Local MinerU Server.
• OpenCode Go is a new provider preset.

v3.9.13

• Side panel in the standalone window holds up to eight tabs: a side chat, past chats, and everything a chat made.
• Files the Agent saves show as preview cards under the answer, and each paper gets its own folder. See Files the Agent Saves.
• Papers outside your library: the Agent can read the abstract and open-access text of a paper from a DOI, PubMed, PMC, or arXiv ID.
• Claude Code works without setup: the plugin starts and stops the bridge that Claude Code needs.
• AI note edits keep citations, highlights, and images in place.
• DeepSeek search is a new choice for web search, next to Tavily and AnySearch.

Earlier updates

• Usage Statistics provides a local overview of Paper chat and Library chat activity, with time filters, activity and token charts, model details, CSV export, and reset controls. See Usage Statistics.
• Built-in web and literature research lets the Agent search the public web, read source pages, and combine current online information with evidence from your Zotero library. Answers can include paragraph-level source cards, while the activity trace keeps general web results and scholarly literature results visually distinct. See General Web Search.
• Codex App Server is the recommended Codex path for ChatGPT Plus users. It runs through the local codex app-server runtime and is configured from the Agent tab.
• Claude Code Mode (experimental) runs Claude Code as a separate conversation system inside Zotero, using your own Claude Code login. It can use the plugin’s Zotero tools to read your library and, with your approval, edit notes, tags, metadata, and imports. See Claude Code Setup.
• One history lists Agent, Codex, and Claude chats together. Click the runtime badge in the message box to switch runtimes, and attach an earlier conversation from the slash menu or by asking for it in plain words.
• WebChat Mode supports ChatGPT, DeepSeek, and Google Gemini web sync through the Sync for Zotero browser extension.
• File-Based Notes: Notes are no longer hard-coded to Obsidian. Configure any local Markdown directory, including Obsidian, Logseq, or a plain folder. See File-Based Notes.
• Skills: Customizable guidance files shape how the agent handles different tasks. 8 built-in skills are included, plus a portal for creating your own. See Skills.
• Standalone Window Mode opens the assistant in a dedicated window with paper chat, library chat, and conversation history.
• Cache-aware Agent Mode preserves stable paper context, prior read evidence, and coverage state across longer research turns, then compacts old transcript history automatically when the context window gets crowded.
• Citation navigation keeps citation labels conservative until page locations are verified, while quote-based citations can jump back to the matching Zotero passage.
• MinerU PDF parsing: High-fidelity extraction preserves tables, equations, and figures more accurately, with support for cloud MinerU, local mineru-api servers, bulk parsing, cache repair, sync packages, tags, and parsing filters.
• Precise Figure Extraction: Figure questions and figure notes now use crops cut directly from the source PDF — with MinerU as the index — instead of MinerU’s own figure images, for sharper, more accurate figures. See Precise Figure Extraction.

Thanks to @jianghao-zhang and @boltma for major contributions to the Codex App Server, Claude Code, and file upload workflows.

Installation

1. Download the latest .xpi release Go to the Releases Page and download the latest .xpi file.

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

3. Restart Zotero Restart Zotero to complete the installation. The plugin automatically checks for future updates on startup.

Configuration

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.

Supported Providers & Protocols

Preset providers include OpenAI, Gemini, Anthropic, MiniMax, GLM, DeepSeek, Grok, Qwen, Kimi, and GitHub Copilot. You can also add any customized OpenAI-compatible HTTP endpoint, including Ollama, LM Studio, vLLM, or a remote proxy.

The plugin natively supports these provider protocols:

Supported Models (Examples)

You can also set up multiple providers, each with multiple models for different tasks, such as a multimodal model for figures and a text model for summaries. Cross-check answers across models when you want broader coverage.

Advanced: Reasoning Levels & Hyperparameters

You can set different reasoning levels per model in the conversation panel, such as default, low, medium, high, and xhigh, depending on model support. You can also adjust hyperparameters like temperature and max_tokens_output for more creative or more deterministic responses.

Usage Guide

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, keeping the conversation fast and relevant.

Conversation Modes

The plugin supports multiple conversation contexts:

Interface Controls

• Model selector — switch between configured models mid-conversation.
• Reasoning selector — choose the reasoning level for the current request.
• Font scaling — adjust sidebar font size from 80% to 180%.
• Auto-scroll — automatically scrolls to the latest message.
• Token usage — real-time display of input, output, and reasoning tokens consumed.

Grounded Answers with Citation Navigation

When you ask a question, the model generates answers grounded in the paper’s content. Citation labels stay conservative until page locations are verified; click a verified citation or quote-based citation to jump back to the matching Zotero passage.

Paper Summarization

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 to focus on methodology, results, implications, or anything else.

Selected Text Explanation

Select any complex paragraph or technical term in the PDF and ask the model to explain it. You can add up to 5 pieces of context from the paper or previous answers to refine the explanation.

An optional pop-up automatically suggests adding selected text to the chat. This can be disabled in settings if you prefer manual control.

Figure Interpretation

Take a screenshot of any figure, chart, or diagram and ask the model to interpret it. The plugin supports up to 10 screenshots at a time.

Cross-Paper Comparison

Open multiple papers in different tabs and compare them side by side. Type / in the chat input to cite another open paper as additional context. You can reference up to 10 papers in a single conversation, enabling rich cross-paper analysis.

External Document Upload

Upload documents from your local drive as additional context. Supported formats include PDF, DOCX, PPTX, TXT, and Markdown.

Save to Notes

Save any answer or selected text directly to your Zotero notes with one click. This integrates seamlessly with your existing note-taking workflow — no copy-pasting required.

Conversation History & Export

Conversations are automatically saved locally and associated with the paper you’re reading. You can:

• Browse past conversations from the history panel.
• Export entire conversations to Zotero notes in Markdown format.
• Exported notes include selected text, screenshots, and properly rendered LaTeX equations.

Usage Statistics

Open Zotero Settings/Preferences → llm-for-zotero → Usage to review activity recorded by the plugin.

Use Overview, Paper chat, and Library chat to move between the combined dashboard and scope-specific details. The 7d, 30d, and All controls filter the summary, daily token chart, model breakdown, and detail lists; the activity heatmap continues to show the available history, up to one year.

• Overview shows question totals, distinct papers and conversations, input/output token totals, a questions-or-papers activity heatmap, tokens per day, and a model breakdown that identifies the provider or runtime and the paper/library split.
• Paper chat lists the papers you asked about most, with question and token totals.
• Library chat lists the heaviest conversations, with their question and token totals.

The panel reports token usage only and does not estimate monetary cost. For conversations from before the Usage tab existed, question and paper activity is reconstructed from stored messages, while token totals are clearly labeled as estimates derived from the stored prompt size and assistant text, including stored reasoning. If a provider does not report tokens, the panel marks those turns as unreported or shows an em dash with an explanation instead of treating them as zero. WebChat turns are excluded from both live statistics and historical reconstruction.

Usage statistics remain in your own Zotero database and are not sent elsewhere by this panel. Export CSV saves the recorded rows for the selected time range, while Reset statistics permanently clears all usage rows without deleting conversations, notes, or papers. Historically reconstructed rows are not rebuilt after a reset.

Custom Quick-Action Presets

Customize quick-action presets to match your research workflow. Built-in presets include:

• Summarize — generate a concise summary
• Key Points — extract main findings
• Methodology — describe the research methods
• Limitations — identify weaknesses or gaps

Standalone Window Mode

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

How to open

Features

• Paper chat & Library chat — Switch between paper-specific and library-wide conversations using the tabs at the top.
• Conversations — Browse past chats in the sortable Conversations list in the left sidebar. You can group them into foldable Agent, Codex, and Claude sections, each with its own sort order and a + button for a new chat. Pinned papers stay at the top, and each one keeps its own side panel tabs.
• Side panel — Open it with the button at the end of the Paper chat | Library chat row. It holds up to eight tabs:
  • Side chat: ask a quick question without leaving the main chat. It sees the main chat, can use a different model, and is not saved.
  • History: read an earlier chat next to the current one, quote it, add its paper, or make it the main chat.
  • Miscellaneous: everything the chats of this paper made, such as diagrams, figures, web pages, code, plans, and files. Go to chat jumps to the message that made it.
  • Task progress: the sources for each question. See Task Progress and Sources.

  Diagrams, code, web pages, figures, plans, and files in the chat have a →| button that moves them into their own side panel tab. Select text in an answer and pick Quote in side chat to ask about it in a side chat.

• Full feature parity — Everything available in the reader sidebar — screenshots, file uploads, agent mode, quick-action presets, reference picker — works identically in the standalone window.
• Search — Search through your conversation history using the search overlay.

While the standalone window is open, the reader sidebar panels show a placeholder with options to Focus Window (bring the standalone window to the foreground) or Close Window & Return Here (close standalone and restore the sidebar).

File-Based Notes

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.

Configuration

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.

How it works

Ask the agent to write a note using the nickname you configured, for example “Summarize this paper and save it to Obsidian” or “Log this to my Logseq”. The agent will:

1. Gather content from the paper, including metadata, summary, key points, and figures when available.
2. Compose a Markdown note following the write-note skill.
3. Add YAML frontmatter matching the write-note template: title, created, tags, citekey, doi, and journal; author information stays in the note body.
4. Embed extracted figure crops — precise crops cut from the source PDF — and copy them into the attachments folder when requested. See Precise Figure Extraction.
5. Write the note to {notes_directory}/{default_folder}/{title}.md.

If you want to keep notes inside Zotero, the agent can also write to internal item notes with the write-note skill. Ask it to “save a note for this paper” without mentioning an external directory.

Zotero Notes vs. File-Based Notes

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

Editing Zotero Notes With the Agent

• Citations, PDF highlights, and images stay intact. The agent sees each one as a placeholder such as {{citation:3fa9c1 ("Smith", 2020, p. 42)}}, and every edit puts the original item back, so a rewrite can move a citation but never break it. An edit that would drop one is refused unless you asked for it to be deleted.
• Clickable citations. Ask for page citations and the agent writes {{cite item=123 page=42}}, which becomes the same citation Zotero’s Insert Citation makes: clicking it opens the PDF at that page.
• Study-note blanks. A line of underscores inside a quote (> ___) becomes a divider, and a checklist item made only of underscores (- [ ] ____) keeps its checkbox as a fill-in blank.

General Web Search

Starting with v3.9.4, Agent Mode can research the public web without leaving Zotero. The Agent can search for current information, open selected source pages for focused reading, and combine those findings with papers, notes, and metadata from your Zotero library. This is useful when a question depends on information that may be newer than a paper or a model’s training data, such as current documentation, organization pages, policies, product information, or recent public reporting.

Set Up Tavily

Web search can use Tavily (the default), AnySearch, or DeepSeek. Tavily uses its own API key, separate from your model-provider key.

1. Create a Tavily account and obtain an API key.
2. Open Zotero → Preferences → llm-for-zotero → Agent.
3. In Web search, keep Tavily, paste the key, and click Test connection.
4. Enable Agent Mode, then ask a question that needs current or public web evidence.

There is no separate on/off switch. The web_search and web_read tools become available to the Agent when the selected provider can run. They are not added to WebChat, Codex, or Claude Code chats, which use their own web search.

Other Search Providers

Select the provider in Preferences → llm-for-zotero → Agent → Web search. For AnySearch, Test search (sends a public query) sends one fixed public query and uses quota. DeepSeek never sends keys of relays or other hosts. Each provider receives your search queries and the URLs the Agent reads.

What the Agent Can Do

General web search and scholarly literature search are complementary rather than interchangeable. Use web search for current documentation, institutional pages, public explanations, standards, policies, and other open-web material. Use literature search when you need academic discovery through OpenAlex, arXiv, and Europe PMC, with Crossref and Semantic Scholar for metadata. The Agent checks your paper and your library first, and searches outside only when they cannot answer. For a broad research question, the Agent can use both and synthesize the results with evidence already in Zotero.

Example Requests

• “Use current web sources to check whether the recommendations in this paper have changed, and show me what changed.”
• “Compare this paper with the latest public guidance from the WHO, and keep paper evidence separate from web evidence.”
• “Research the current state of representational drift, using both recent academic literature and reliable public research pages.”
• “Read this URL, compare its claims with the papers in my current Zotero collection, and cite each source near the claim it supports.”

You do not need to specify a search depth in ordinary requests. The Agent can choose between basic and advanced search based on the question, or you can ask explicitly for a broader or deeper search when coverage matters more than credit use.

Credits, Privacy, and Verification

Tavily usage consumes Tavily credits. The v3.9.4 preferences panel shows the release-time credit model: basic search uses 1 credit, advanced search uses 2 credits, and extraction is charged per five successfully read pages. At the time of writing, Tavily’s free plan provides 1,000 credits each month without requiring a credit card. Allowances and pricing can change, so consult Tavily’s credit and pricing documentation and your account for the current terms.

Search queries and requested URLs are sent to Tavily under Tavily’s privacy, retention, and search-index policies. When results are displayed, Zotero may load favicons from public URLs supplied by Tavily. Do not include credentials, unpublished material, personal data, or other sensitive private text in a web query.

Web sources can change or disagree. Use the source marks to open important pages and verify high-stakes claims against the original source before relying on them.

Agent Mode (Beta)

In a normal chat, the model answers from the context you give it. In Agent Mode, the model can also use tools: small actions that read, search, or change your Zotero library. You ask in plain words, and the Agent decides which tools to use and in which order.

The rule is simple: tools that only read run directly; tools that change something wait for your approval and can be undone.

How an Agent Run Works

1. You ask. For example: “Find the papers in this collection that use calcium imaging, tag them, and write a summary note.”
2. The Agent splits the request into parts and tracks each part, so a long request does not lose a step.
3. The Agent reads. It searches your library, reads papers and notes, and searches outside sources only when your library cannot answer.
4. The Agent proposes changes. A tag, a metadata edit, a note, or a command shows as a confirmation card. Nothing changes until you approve it.
5. The Agent answers. Cited sentences end with a numbered mark, and the task progress panel shows what each answer used.
6. You can undo. Ask the Agent to undo, and it reverts recorded changes, newest first.

If a choice is unclear, such as which collection to use, the Agent asks you before it continues.

Long agent runs are cache-aware. The plugin keeps stable Zotero context and previously read evidence separate from the changing chat transcript, tracks which papers and passages have already been inspected, and automatically compacts old turns when the model context fills up. Follow-up questions can reuse grounded evidence when it is still relevant, while the agent reads again when the needed source or coverage layer is missing.

Task Progress and Sources

Task progress opens in a side panel tab of the standalone window. It has one block for each question, with the papers and web pages that question used.

• For a library paper, it lists the passages the Agent read, then where the answer uses them.
• For a web page, it shows the page with the site’s icon. Web links open in the side panel.
• Show in answer finds the sentence that cites a source, highlights it, and scrolls to it.

Use it to check what the Agent read before you trust an answer. It works in paper chat and in library chat.

Papers Outside Your Library

The Agent can read a paper that is not in your library, from a DOI, PubMed ID, PMC ID, or arXiv ID. It reads the full abstract, and the full text when the paper is open access. For a paper that is only available as a PDF, it gives you the link. Reading never imports the paper; ask the Agent to import it if you want to keep it.

Earlier Conversations

The Agent can find, read, and attach an earlier chat, up to three at a time. Type / and pick Add past conversation, or just ask, for example “add the chat where I asked about grid cells last week.” This works in Agent, Codex, and Claude modes.

Files the Agent Saves

When the Agent saves a file, such as a web page, a Markdown summary, a picture, or a table, a preview card shows under the answer. From the card you can open the file in the full view, show it in its folder, or move it to the side panel. The card stays if you delete the file later, and says that the file is gone.

Each paper gets its own folder for saved files. In Preferences → llm-for-zotero → Agent → Saved files, you can choose where these folders go. Check folders lists them with their size, shows folders of deleted papers first, and lets you delete the ones you no longer need.

Agent Tools

You do not need to call these tools yourself; the Agent picks them. The table helps you understand the activity trace and the confirmation cards.

Example use cases:

• Run a Python or R script to analyze data extracted from your library.
• Export metadata as CSV/JSON for external processing.
• Invoke CLI tools (e.g. pandoc, ffmpeg, pdftotext) as part of an agent workflow.
• Write and execute scripts dynamically to transform or visualize your research data.
• Read local data files and incorporate results back into Zotero notes.

Built-in Actions

The agent provides high-level actions for common library workflows. These chain multiple tools together automatically.

MCP Server

The plugin runs a built-in Model Context Protocol (MCP) server, allowing external AI agents and tools to interact with your Zotero library programmatically.

• Endpoint: http://localhost:23119/llm-for-zotero/mcp
• Protocol: JSON-RPC 2.0 (MCP v2024-11-05)
• Methods: initialize, tools/list, tools/call

This means you can connect any MCP-compatible AI agent (e.g. Claude Desktop, Cursor, custom agents) to your Zotero library and use all the tools listed above.

Agent Demos

Multi-step workflow

The agent can chain multiple tools together to accomplish complex tasks, such as finding a paper, reading its metadata, searching for related work, and writing a summary note.

Find related papers

There are two ways to find related papers:

• /discover_related runs a direct OpenAlex search for the paper you are viewing. It does not need a model. It opens Recommendations, References, and Citations tabs with up to 20 papers each. Use /discover_related 30 to change the number, Load more for 20 more, and Import selected to save the papers you choose.
• Ask in chat, for example “find relevant papers” or “find 15 relevant papers.” The Agent ranks the candidates and gives a reason for each. It starts with five unless you give a number. Use Find more for another batch and Import selected to save your choice. If fewer good matches exist, the card says so instead of padding the list.

Apply tags automatically

Write a note

Safety & Confirmation

All write operations go through a human-in-the-loop confirmation workflow:

• The agent proposes a batch of changes (e.g. add tags, edit metadata).
• You review the proposed changes in a rich approval form.
• You can approve, reject, or modify before any changes are applied.
• If something goes wrong, ask the agent to undo; the undo tool reverts recorded write actions newest-first.
• Terminal commands and file operations also require explicit approval before execution.

Skills

Skills are customizable guidance files that shape how the agent approaches different types of requests. A skill teaches the Agent how to do a task, such as which tools to use and in which order; it does not add new tools. Each skill is a Markdown file with a short description and a body of instructions.

Built-in Skills

The plugin ships with 8 built-in skills covering common research workflows. They are automatically copied to your skills folder on first run.

How Skills Work

1. At the start of each turn, the Agent sees only the name and description of each skill.
2. If the Agent decides that the task needs a skill, it calls load_skill to read the full instructions. There is no automatic pre-selection.
3. If you pick a skill from the / menu, the plugin applies it directly.
4. A skill applies only in the contexts its file allows, such as one paper or a whole library.
5. An approved plan keeps the exact skill versions it was approved with.

Because the Agent chooses skills from their descriptions, a clear and precise description matters more than anything else in a custom skill.

Creating Custom Skills

1. Open the Standalone Window (Ctrl+Shift+L / macOS: Cmd+Shift+L).
2. Click the Skills icon in the top toolbar to open the Skills portal.
3. Click the ”+ New skill” button to create a template file.
4. The template opens in your default text editor. Edit the frontmatter and the instructions:

---
name: my-custom-skill
id: my-custom-skill
description: Describe what this skill does
version: 1
contexts: any
activation: auto
---

Describe precisely when and how the agent should apply this workflow.

5. Save the file. The skill is loaded immediately — no restart needed.

Skill file format:

Managing Skills

• Left-click a skill in the portal to open it in your default text editor.
• Right-click a skill for a context menu with Show in file system and Delete options.
• Skills are stored in {ZoteroDataDir}/llm-for-zotero/skills/ as .md files.
• If you delete a built-in skill, it stays deleted across restarts — the plugin respects your choice. New built-in skills added in plugin updates are seeded automatically without restoring skills you removed.

WebChat Setup (ChatGPT, DeepSeek & Gemini Web Sync)

WebChat mode sends your questions to chatgpt.com, chat.deepseek.com, or gemini.google.com through a browser extension, then streams responses back into Zotero. It is useful when you want browser-chat access without a provider API key.

Prerequisites

• Access to the selected provider site. Account requirements depend on the site and feature; Gemini may allow anonymous text conversations, while PDF upload and conversation history may require sign-in.
• A Chromium-based browser such as Chrome, Edge, Brave, or Arc.

Step-by-step setup

1. Download the browser extension:

Go to github.com/yilewang/sync-for-zotero → Releases, download the latest extension.zip, and unzip it 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:

In Zotero → Preferences → llm-for-zotero:

4. Start chatting:

Open the matching ChatGPT, DeepSeek, or Google Gemini tab in your browser and keep it open. For Gemini, open gemini.google.com/app and choose the Gemini model on the website; the Zotero bridge does not change the site’s model selection. In Zotero, the plugin panel shows a WebChat indicator with a connection dot (green = connected, red = not detected). Type a question and send.

WebChat features

• 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 web conversations.
• Exit — Click the “Exit” button to return to regular API mode.

Gemini notes

• Use the latest paired releases of llm-for-zotero and Sync for Zotero. Older browser-extension builds do not advertise Gemini support and Zotero will stop the request before sending it.
• Gemini WebChat can send one PDF per request and can also attach screenshots. Wait for the attachment preview to finish loading before sending.
• If Gemini’s composer still contains an attachment from an earlier attempt, remove it before retrying. If Zotero says a send could not be verified, inspect the Gemini tab before retrying to avoid submitting the same prompt twice.
• Gemini responses and history are read from the rendered page, so a Gemini website update may temporarily require a Sync for Zotero adapter update.

Technical Notes

• The plugin embeds a lightweight HTTP relay server on Zotero’s built-in port (23119). The browser extension polls this relay to exchange queries and responses.
• Agent mode, slash commands (/), and the reference picker (@) are disabled in WebChat mode.
• Reasoning/thinking mode is controlled on the web app side, not through the plugin’s reasoning toggle.

Codex Setup (ChatGPT Plus Subscribers)

If you have a ChatGPT Plus subscription, you can use Codex models in the plugin without a separate API key by signing in through the Codex CLI.

New users should choose Codex App Server from the Agent tab. The older Codex Auth (Legacy) path remains available for existing users, but is planned for future deprecation after app-server validation.

• Codex App Server (Recommended): Spawns the local codex app-server CLI and talks to it over stdio. This is the official way to use Codex in third-party apps and the preferred setup for new users. It is configured from the Agent tab and appears as a dedicated Codex button in the chat header.
• Codex Auth (Legacy): Uses the ChatGPT/Codex Responses backend directly. Existing users can keep this configuration for now, but new users should choose Codex App Server.

Special thanks to @jianghao-zhang for contributing the original Codex Auth integration, and to @boltma for designing the Codex App Server integration.

Step-by-step setup

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

# macOS / Linux (requires Node.js 18+)
npm install -g @openai/codex

# macOS alternative (no Node.js needed)
brew install --cask codex

On Windows, install Codex from PowerShell or Command Prompt rather than WSL, so Zotero MCP can use the Windows-local loopback connection.

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. Enable Codex App Server in Zotero:

Open Zotero → Preferences → llm-for-zotero → Agent tab:

Click Test connection to verify that Zotero can launch codex app-server, then click the Codex button in the chat header to enter the Codex conversation system.

Codex App Server and Claude Code are mutually exclusive runtime modes in the Agent tab. Disable one before enabling the other.

Existing users who need the old path can open the AI Providers tab, choose Codex Auth (Legacy), keep API URL https://chatgpt.com/backend-api/codex/responses, and use the same Codex model name, for example gpt-5.5.

Codex Auth (Legacy) Technical Notes

• Reads local credentials from ~/.codex/auth.json (or $CODEX_HOME/auth.json).
• Automatically attempts token refresh on 401 responses.
• Embeddings are not supported in legacy direct 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.

Claude Code Setup (Experimental)

Claude Code mode runs Claude Code as a separate conversation system inside Zotero. It reuses the sidebar and standalone-window UI, but has its own paper / open scope state, model and reasoning settings, permission semantics, slash commands, and project skills. Claude chats appear in the same history list as your other chats, with a small Claude label.

Special thanks to @jianghao-zhang, who built the Claude Code integration and its bridge (cc-llm4zotero-adapter). The bridge now ships inside the plugin, with the author’s permission, under packages/claude-bridge.

Prerequisites

You need two things on your computer. The plugin takes care of the rest.

• Node.js 18 or newer. Download it from nodejs.org (the LTS version is fine), or use a version manager such as NVM, Volta, or Homebrew. Check it in a terminal with node --version.
• Claude Code, installed and logged in. Follow Anthropic’s installation and authentication guides. You can use your Claude subscription or an API key.

1. Install and Log In to Claude Code

In a terminal, run:

claude

Finish the login steps it shows, then close it. You only need to do this once.

2. Turn On Claude Code Inside Zotero

Open Zotero → Preferences → llm-for-zotero → Agent tab, and switch on Claude Code. Recommended settings:

Then click the Claude Code button in the chat header, or click the runtime badge in the message box and pick Claude, to enter Claude Code mode.

That is all. You do not need to download or start a bridge yourself. While Claude Code mode is on, Zotero starts a small helper program (the “bridge”) that connects Zotero to your Claude Code. It runs only on your computer, only answers Zotero, and stops when you quit Zotero or turn Claude Code off. If you never turn on Claude Code, nothing extra runs.

The Bridge section at the top of the Claude Code settings shows whether the bridge is running. Use Restart bridge if something seems stuck, and Open log to see what the bridge reported.

Keep Config source on default unless you already understand Claude Code settings layers. In default, Claude Code can use your normal user settings plus Zotero-managed project and per-conversation local settings. The other options are:

• user-only: only your machine-wide Claude settings.
• zotero-only: only Zotero-managed project and local settings.

3. If It Does Not Work

The Bridge status line says what is wrong in plain words. The usual causes:

Zotero opened from the Dock or Start menu does not always see the same programs as your terminal. The plugin looks in the usual places (NVM, Volta, Homebrew, ~/.local/bin, and the Claude Code installer’s folder), but the two path settings are there if it still cannot find them.

Advanced options

• Extra bridge options passes command-line options to the bridge, for example --additional-directories ~/Papers to let Claude read another folder, or --append-system-prompt-file ~/zotero-claude.md. Press Restart bridge after changing it.
• Use my own bridge is for people who run the bridge themselves, for example inside WSL while Zotero runs on Windows, or on another computer. Zotero then sends Claude requests to the Bridge URL and does not start its own bridge. The bridge’s code lives in packages/claude-bridge; see its README for how to run it by hand.

Upgrading From the Old cc-llm4zotero-adapter

Earlier versions needed the separate cc-llm4zotero-adapter repository and npm run serve:bridge or npm run daemon:*. That is no longer needed. Your Claude Code conversations, skills, and settings keep working, because the new bridge uses the same ~/Zotero/agent-runtime and ~/Zotero/agent-state folders.

If you installed the old macOS background service, it can stay, since it does not get in the way, but it is no longer used. Zotero tells you once if it finds it. To remove it, run this in your old adapter folder:

npm run daemon:uninstall

If you already deleted that folder, run these two commands instead:

launchctl bootout gui/$(id -u)/com.toha.ccbridge
rm ~/Library/LaunchAgents/com.toha.ccbridge.plist

4. Claude Project Skills and Commands

Zotero creates a Claude runtime root under your home directory, usually shaped like:

~/Zotero/agent-runtime/profile-.../

Shared Claude project assets live in:

CLAUDE.md
.claude/settings.json
.claude/skills/
.claude/commands/

Each Claude conversation also gets its own local .claude folder under the runtime scopes/ tree, so per-conversation overrides do not leak into other chats.

Models and Non-Anthropic Setups

The Zotero UI loads the model catalog advertised by the Claude Code bridge and preserves each model value exactly, including aliases, explicit model IDs, context-window variants, custom provider values, and future model families. The chat model picker identifies the active conversation, so model discovery uses the same scoped .claude/settings.local.json stack as the turn. The model preference remains editable when discovery is unavailable. Claude Code is responsible for resolving or rejecting the selected value and for applying provider or proxy configuration.

MinerU PDF Parsing

MinerU is an advanced PDF parsing engine that extracts high-fidelity Markdown from PDFs while preserving tables, equations, figures, and complex layouts that standard text extraction often mangles.

Parsed results are cached locally and reused in later conversations. When Auto-parse newly added items is enabled, newly added PDF attachments are sent to MinerU as they enter the Zotero library. If auto-parse is off, you can still parse selected or filtered PDFs from the Manage Files panel.

The MinerU cache is designed for AI, not as a second human PDF reader. Zotero stays the place where you read, annotate, and manage the original PDF. MinerU creates structured sidecar material that models can use: clean Markdown, section ranges, page hints, tables, equations, and extracted figure assets. This keeps the original Zotero UI mostly untouched while giving the assistant much better paper context than raw PDF text extraction.

For figure questions, MinerU acts as the index that locates each figure, while the image the model actually sees is a precise crop taken from the source PDF; see Precise Figure Extraction.

How to Enable MinerU

1. Open Zotero → Preferences → llm-for-zotero.
2. Find the MinerU section and check Enable MinerU.
3. Keep cloud mode enabled, or check Use local MinerU server for local mode.
4. For cloud mode, optionally enter your own MinerU API key.
5. For local mode, run a self-hosted mineru-api server and keep the default base URL (http://127.0.0.1:8000) unless your server uses a different address.
6. To parse new imports automatically, check Auto-parse newly added items. Then add or import a PDF into your Zotero library. The plugin will parse newly added PDF attachments with MinerU and cache the result for future conversations.

Using Your Own API Key

MinerU can start without an API key through the built-in API, but a personal key is strongly recommended. The built-in API may no longer be supported after June 1, 2026.

To get a free personal key:

1. Go to mineru.net and create an account.
2. Generate an API key in your account settings.
3. Paste the key into Zotero → Preferences → llm-for-zotero → MinerU.
4. Click Test Connection to verify.

When a personal API key is provided, the plugin calls the MinerU API directly at https://mineru.net/api/v4.

Using a Local MinerU Server

Local MinerU server support was contributed by @renyong18 in PR #152.

Local mode sends PDFs to a self-hosted mineru-api server through POST /file_parse and stores the returned ZIP output in the same local cache format as cloud parsing. The default base URL is http://127.0.0.1:8000.

Prerequisites for local mode:

1. Install MinerU and run mineru-api; see the MinerU docs for installation.
2. Make sure required models are downloaded. mineru-api lazy-loads on first request, so the first parse after starting the server or switching backend can take noticeably longer than steady state.

You can pick a Backend in the local section:

• pipeline (default) — general-purpose, multi-language, CPU-friendly.
• vlm — VLM-based, high accuracy on Chinese/English documents, requires GPU.
• hybrid — newer high-accuracy hybrid pipeline, multi-language, requires local compute.

Test Connection checks that the server process responds at /health; it does not guarantee that all models are warmed up.

Start and stop the server automatically (contributed by @AkimioJR in #530):

• Enter the command that starts the server, for example mineru-api.
• The plugin starts the server when it parses a PDF.
• It stops the server after a set idle time, to free memory and GPU memory. The default is 10 minutes.
• Preferences show the server status, with Start and Stop buttons.
• The server also stops when you quit Zotero.

With the default 127.0.0.1 address, PDFs stay on your machine. If you change the base URL to a LAN or remote server, PDFs are sent to that server.

Pause / cancel limitation: mineru-api exposes no cancel or DELETE endpoint, only POST /file_parse, POST /tasks, GET /tasks/{id}, GET /tasks/{id}/result, and GET /health. When you click Pause, the plugin stops the queue and aborts the HTTP wait, but the parse already running on the server keeps executing until it finishes, so GPU/CPU work will not stop immediately. Restart the mineru-api process yourself if you need to abort immediately, such as when switching backend without waiting.

Managing MinerU Caches

The MinerU preferences tab includes a Manage Files panel for maintaining parsed PDF caches:

• Browse cached and uncached PDFs by collection, tag, title, author, year, and added date.
• Start parsing all visible files, only filtered files, or selected files.
• Repair local MinerU caches and synced packages when metadata or files drift.
• Delete all, filtered, selected, or single-item caches from the manager.
• Use tag filters, including automatic Zotero tags, to choose which papers are included in bulk actions.

Automatic cache management is event-driven. The plugin watches Zotero item additions, finds PDF attachments on regular items or standalone PDFs, and waits briefly before processing so Zotero can finish importing the file. If the Zotero item exists but the PDF file path or parent attachment list is not ready yet, the queue retries after short delays instead of failing immediately. Deleted attachments are removed from the queue, and already cached PDFs are skipped.

The queue respects the same filters as bulk parsing. It skips PDFs that already have a local MinerU cache or an available synced package, avoids duplicate queue entries, and shows live status through the MinerU dots: ready, processing, or failed. A normal metadata edit does not repeatedly reparse a finished PDF; modify events are mainly used to recover in-progress, failed, or file-readiness cases.

When a parse succeeds, the plugin writes a cache under Zotero’s data directory in llm-for-zotero-mineru/<attachmentId>/. The canonical files include full.md, manifest.json, content_list.json, extracted assets such as images, and _llm_source.json provenance. The manifest is built for AI access: it maps section titles to character ranges, page hints, and section-level figures so the agent can read the relevant slice of full.md instead of loading the whole paper for every question.

After writing a MinerU cache, the plugin clears stale in-memory text and embedding caches for that PDF. The next question can then use MinerU-quality chunks and regenerate retrieval data from the better parsed text.

Advanced parsing filters can skip files before automatic or bulk parsing:

• Skip files over N pages controls the maximum page count used by Start All, Start Filtered, Start Selected, and auto-parse. The default is 100 pages.
• Exclude PDFs by Filename accepts comma-separated substrings, or regex patterns wrapped in /slashes/, for translated copies, supplements, or other files you do not want parsed automatically.

If Sync MinerU cache with Zotero file sync is enabled, the plugin can create companion ZIP attachments containing full.md, manifest.json, content_list.json, and extracted assets. Sync is optional and default-off. Existing local caches sync only when you request it from the MinerU tab, and synced packages can restore a missing local cache when needed. The repair path validates package metadata and content hashes, prunes duplicate packages for the same source PDF, removes orphaned local caches, and restores usable local cache folders from synced ZIP packages.

Precise Figure Extraction

When Agent Mode answers a question about a figure — or saves a note that discusses one — it pulls a precise, high-resolution crop straight from the source PDF, using the MinerU cache only as an index. Ask something like “What does Figure 3 show?” and the agent locates the figure from the MinerU parse, cuts a clean crop from the original PDF page, and reads that exact image, caption and panels included.

This is different from Figure Interpretation, where you take the screenshot yourself. Here the agent finds and crops the figure for you, and those same crops are what get embedded when you save a figure to your notes.

Good to know:

• No setup. Crops are produced by a small extraction runtime that the plugin downloads and manages per platform, so you never install Python or any other tool yourself.
• Figures, not tables. Tables are read as structured Markdown text from the MinerU parse, so figure extraction skips them by design.
• Requires a MinerU cache. Figure extraction needs the paper to be parsed by MinerU first. Without a cache, the agent falls back to captions and surrounding text and tells you it could not extract the figure image.

Privacy and Data Flow

• In standard provider mode, paper content and user messages are sent to the model provider you configure.
• In local-model mode, requests go to the local OpenAI-compatible endpoint you configure.
• In WebChat mode, requests are relayed through the browser extension to chatgpt.com, chat.deepseek.com, or gemini.google.com.
• In cloud MinerU mode, PDFs selected for automatic or manual MinerU parsing are sent to MinerU.
• In local MinerU mode, PDFs selected for automatic or manual MinerU parsing are sent to the local or remote mineru-api server you configure.
• In Codex App Server and Claude Code modes, requests go through your local codex or Claude Code installation to OpenAI or Anthropic.
• With general web search, search queries and the URLs the Agent reads are sent to the provider you select: Tavily, AnySearch, or DeepSeek.
• Scholarly search sends search terms and paper identifiers to OpenAlex, arXiv, Europe PMC, Crossref, and Semantic Scholar.
• Conversation history, cached paper context, usage statistics, and files the Agent saves are stored locally by the plugin.
• Agent Mode write operations are routed through reviewable actions and session undo where supported.

Troubleshooting

For bugs or unclear failures, please open an issue.

Roadmap

• Agent mode (beta)
• MinerU PDF parsing
• GitHub Copilot auth
• WebChat mode (ChatGPT, DeepSeek, and Google Gemini web sync)
• Standalone window mode (#78)
• File-based notes (Obsidian, Logseq, any Markdown directory)
• Claude Code integration
• Codex App Server integration
• Customized skills
• Local MinerU support
• Cross-device synchronization (MinerU cache)
• Agent memory system

Frequently Asked Questions

Is it free to use?

Yes, the plugin is completely free and open source (AGPL v3). You only pay for API calls to your chosen provider. With Codex App Server, ChatGPT Plus subscribers can use their existing subscription without a separate API key.

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.

Is my data used to train models?

The plugin does not train models. Data handling depends on the backend you choose: your configured API provider, local model, WebChat, Codex, Claude Code, or MinerU.

How do I report a bug or request a feature?

Please open an issue on GitHub.

Contributing & Support

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

If you find this plugin helpful, consider:

• Leaving a star on GitHub
• Buying me a coffee
• Donating via Alipay QR code below:

Star History