Zotero AI Butler: an LLM reading pipeline inside your Zotero library

The backlog problem Zotero AI Butler is aimed at

Zotero collects papers faster than anyone reads them. The README states the case bluntly: a paper saved for later reading becomes a paper never read. The plugin's answer is to move the first pass out of your hands. You drop a PDF into Zotero as usual, and the plugin reads it and files a Markdown note under the same item. The stated audience is the researcher with a crowded library who would otherwise paste papers into a chat window one at a time. The README lists three complaints it targets: too many papers to get through, forgetting a paper two days after finishing it, and losing the thread in long PDFs even with a translation plugin open. The project is a third-party Zotero plugin, not a service. It ships no proxy and no hosted model access. You supply the API key, and the README's privacy note says the plugin does not collect, store or upload your data, papers or keys, with requests going from your machine to the provider you configured.

How the note gets written: queue, provider, PDF mode

The architecture visible in the README is a producer-consumer queue. Items enter the queue through one of three triggers and a worker drains it at a rate you set, expressed as papers per minute, so a slow or rate-limited endpoint does not get hammered. The dashboard has a task queue page showing pending, running, finished and failed jobs, and a details view that streams the model's response while a task runs. Each job resolves to one configured provider. The README's table lists Google Gemini (gemini-3-pro-preview is the recommended entry), OpenAI (gpt-5), Anthropic (claude-opus-4-5-20251101), OpenAI-compatible endpoints using the Chat Completions format for third parties such as SiliconFlow, Volcano Ark with doubao-seed-1-8-251228, and Ollama for local or LAN models. PDF handling is a separate switch. Multimodal mode uploads the PDF as Base64 so the model sees the original layout, which the README says helps with formulas, figures and tables and allows purely image-based PDFs to be read. Text extraction mode is the fallback for models without multimodal input; the README notes Ollama uses text extraction or MinerU. Prompts are templates with variables such as {{title}} and {{authors}}, and the editor previews the substitution in real time. There is also a multi-round mode where each round has its own prompt (background, method, experiments, conclusion) and the rounds are merged into one summary.

Installing Zotero AI Butler and running a first paper

The README points to the releases page as the distribution channel; the plugin is installed into Zotero as an add-on, and the project's homepage field also points at the releases page. The README does not spell out the click path for installing an .xpi, so check the release notes for the Zotero version each build targets before you install.

Once installed, open the settings and fill in a provider. The dashboard opens either from Edit, Settings, AI管家 or from the right-click menu item AI管家仪表盘. The README describes a test connection button next to the key fields.

# .env is for plugin development, not for end users.
# Copy .env.example to .env and fill in the values:
ZOTERO_PLUGIN_ZOTERO_BIN_PATH = /path/to/zotero.exe
ZOTERO_PLUGIN_PROFILE_PATH = /path/to/profile

For normal use you do not touch .env. That file exists so the plugin can be built and loaded into a development profile; the example file also carries provider variables such as AIBUTLER_PROVIDER=google, GEMINI_API_KEY and GEMINI_MODEL.

If you want to build from source instead of downloading a release, the package scripts are the entry point.

npm install
npm start

The start script runs zotero-plugin serve, which needs the Zotero binary path and a development profile from .env. The build script runs zotero-plugin build followed by tsc --noEmit, and a prebuild step checks i18n files first.

For a first real paper, right-click the item and choose the menu entry the README gives as 召唤AI管家进行分析. The task enters the queue immediately and you can open the details panel to watch the response. Expect a note to appear under the item when the job finishes; the README says note behaviour matches native Zotero notes. Automatic scanning of new items is off by default to limit the load on Zotero, and is switched on in the dashboard under interface settings, where the README says the choice persists across restarts.

Where it breaks: rate limits, overwrites and cost you own

The failure modes follow from the design. Every job is an API call you pay for, and the README offers no cost estimate or token accounting, so a batch run over a large backlog is an open-ended bill on a metered provider. The plugin's own throttling is the papers-per-minute setting, which is a blunt instrument: it does not know how long a given PDF is. Re-reading a paper through the multi-round menu forces an overwrite of the existing AI note, per the README, which means the old summary is gone rather than versioned. The README does not document rollback or note history for that case. Multimodal mode sends the whole PDF as Base64, which is convenient for layout but pushes far more tokens than extracted text, so the cheaper mode and the more accurate mode are a real trade-off rather than a setting to leave alone. Ollama is listed as a provider, but the README pairs it with text extraction or MinerU, so the local path is not the same experience as a hosted multimodal model. Finally, the release line is beta: the newest releases listed are v4.1.0-beta.2 and v4.1.0-beta.1, both dated 2026-07-29, with v4.0.3-beta.8 before them. A beta plugin that rewrites notes in your library is a different risk class from a read-only tool.

Against Zotero GPT and plain chat windows

The obvious alternative is a general Zotero LLM plugin, the kind people search for under names like Zotero GPT, and the difference is scope rather than model access. A chat-style plugin gives you a box to ask questions about the paper you have open; it does not scan a library, does not queue work, and does not write a note back onto the item. Zotero AI Butler is a pipeline: trigger, queue, provider call, note written to the item, with a dashboard for the backlog. The other alternative is doing it by hand in a browser tab, which is exactly the workflow the README complains about, one paper at a time. What the pipeline costs you is control over the individual pass: a chat window lets you steer every prompt interactively, while the queue runs your saved template and you read the result afterwards. The plugin does expose prompt templates and a follow-up chat panel for追问, but the first pass is automated by design.

Maintenance, AGPL-3.0 and what that means for a plugin

The repository is not archived and the last push was on 2026-09-07, so the project is being worked on rather than parked, but the release channel is beta and the version in package.json is 4.1.0-beta.2. Treat upgrades as re-installs you should test on a copy of your library data before trusting them with a large batch. The licence is AGPL-3.0-or-later, declared in package.json with the LICENSE file at the repository root. AGPL-3.0 is a strong copyleft licence, and the practical question for a Zotero plugin is whether you only install it (which the licence permits) or fork and distribute it. If you modify and distribute the plugin, or run a modified version as a network service, the licence's source-availability terms apply. This is not legal advice; read the LICENSE file and the Zotero plugin distribution conventions yourself if you plan to publish a fork.

Editorial conclusion

Adopt it if you already hold a model API key, keep a large Zotero library, and accept that the current release line is versioned 4.1.0-beta.2. Do not adopt it if you need a supported production tool, if you work offline, or if you cannot send unpublished manuscripts to a third-party endpoint. Before installing, verify two things on the release page: which Zotero version the .xpi targets, and whether the beta you are downloading matches the model provider you intend to use.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. steven-jianhao-li/zotero-AI-Butler on GitHub