[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74995":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":36,"readmeContent":37,"aiSummary":38,"trendingCount":16,"starSnapshotCount":16,"syncStatus":39,"lastSyncTime":40,"discoverSource":41},74995,"llm-for-zotero","yilewang\u002Fllm-for-zotero","yilewang","A research agent system deeply rooted in your Zotero library.","https:\u002F\u002Fyilewang.github.io\u002Fllm-for-zotero",null,"TypeScript",1897,92,3,75,0,73,176,640,219,103.91,"GNU Affero General Public License v3.0",false,"main",true,[27,28,29,30,31,32,33,34,35],"academic-paper","codex","literature-analysis","llm-agent","mcp","rag","research-tool","zotero","zotero-plugin","2026-06-12 04:01:16","# llm-for-zotero: A Research Agent System for your Zotero Library\n\n[![zotero target version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FZotero-7-green?style=flat-square&logo=zotero&logoColor=CC2936)](https:\u002F\u002Fwww.zotero.org)\n[![zotero target version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FZotero-8-green?style=flat-square&logo=zotero&logoColor=CC2936)](https:\u002F\u002Fwww.zotero.org)\n[![zotero target version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FZotero-9-green?style=flat-square&logo=zotero&logoColor=CC2936)](https:\u002F\u002Fwww.zotero.org)\n[![Using Zotero Plugin Template](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FUsing-Zotero%20Plugin%20Template-blue?style=flat-square&logo=github)](https:\u002F\u002Fgithub.com\u002Fwindingwind\u002Fzotero-plugin-template)\n[![License: AGPL v3](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-AGPL_v3-blue.svg?style=flat-square)](https:\u002F\u002Fwww.gnu.org\u002Flicenses\u002Fagpl-3.0)\n[![Latest release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fyilewang\u002Fllm-for-zotero?style=flat-square)](https:\u002F\u002Fgithub.com\u002Fyilewang\u002Fllm-for-zotero\u002Freleases)\n[![GitHub Stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fyilewang\u002Fllm-for-zotero?style=flat-square)](https:\u002F\u002Fgithub.com\u002Fyilewang\u002Fllm-for-zotero\u002Fstargazers)\n[![GitHub Downloads](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fdownloads\u002Fyilewang\u002Fllm-for-zotero\u002Ftotal?style=flat-square)](https:\u002F\u002Fgithub.com\u002Fyilewang\u002Fllm-for-zotero\u002Freleases)\n[![buymeacoffee](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSupport-Buy%20Me%20A%20Coffee-FF813F?style=flat-square&logo=buy-me-a-coffee&logoColor=white)](https:\u002F\u002Fbuymeacoffee.com\u002Fyat.lok)\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Flabel.png\" alt=\"LLM for Zotero logo: a brain icon merged with the Zotero shield\" width=\"512\" \u002F>\n\u003C\u002Fp>\n\n**llm-for-zotero** brings Large Language Models into the Zotero reader, so\nyou can ask questions, summarize papers, inspect figures, compare sources,\nand save notes without leaving your library. It works with standard API\nproviders, local OpenAI-compatible models, WebChat, Codex App-Server,\nand Claude Code.\n\nDocumentation:\n\n- [English](https:\u002F\u002Fyilewang.github.io\u002Fllm-for-zotero)\n- [Chinese](https:\u002F\u002Fyilewang.github.io\u002Fllm-for-zotero\u002Fzh\u002F)\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fdemo.png\" alt=\"Screenshot of the llm-for-zotero sidebar inside the Zotero PDF reader\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fdemo2.png\" alt=\"Screenshot of the llm-for-zotero sidebar inside the Zotero PDF reader\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\n## Table of Contents\n\n- [At a Glance](#at-a-glance)\n- [Quick Start](#quick-start)\n- [What's New](#whats-new)\n- [Configuration](#configuration)\n- [Demos](#demos)\n- [File-Based Notes](#file-based-notes)\n- [Agent Mode](#agent-mode-beta)\n- [Skills](#skills)\n- [WebChat Setup](#webchat-setup-chatgpt-web-sync)\n- [Codex Setup](#codex-setup-chatgpt-plus-subscribers)\n- [Claude Code Setup](#claude-code-setup-experimental)\n- [MinerU PDF Parsing](#mineru-pdf-parsing)\n- [Privacy and Data Flow](#privacy-and-data-flow)\n- [Roadmap](#roadmap)\n- [FAQ](#faq)\n- [Contributing](#contributing)\n- [Star History](#star-history)\n\n## At a Glance\n\n- Chat with the current PDF, selected text, figures, screenshots, and uploaded\n  documents directly inside Zotero.\n- Get grounded answers with citations that jump back to the source passage.\n- Compare multiple open papers or add external files as extra context.\n- Save answers, full conversations, and research notes to Zotero notes or local\n  Markdown folders such as Obsidian and Logseq.\n- Enable Agent Mode for library-wide read, search, tagging, metadata, import,\n  note-editing, and organization workflows.\n- Use your preferred backend: API keys, local models, ChatGPT WebChat, Codex App\n  Server, or Claude Code.\n\n\u003Ca id=\"installation\">\u003C\u002Fa>\n\u003Ca id=\"usage-guide\">\u003C\u002Fa>\n\n## What's New\n\n- **Codex App Server** is the recommended Codex path for ChatGPT Plus users.\n  It runs through the local `codex app-server` runtime and is configured from\n  the **Agent** tab.\n- **Claude Code Mode** runs Claude Code as a separate conversation system inside\n  Zotero through a companion local bridge. It is experimental and does not yet\n  support native Zotero API operations.\n- **Skills** let you customize how Agent Mode handles research workflows. The\n  plugin ships with 8 built-in skills and a portal for creating your own.\n- **Standalone Window Mode** opens the assistant in a dedicated window with\n  paper chat, library chat, and conversation history.\n- **File-Based Notes** save Markdown notes to local folders, including Obsidian,\n  Logseq, or any plain Markdown directory.\n- **Cache-aware Agent Mode** preserves stable paper context, prior read\n  evidence, and coverage state across longer research turns, then compacts old\n  transcript history automatically when the context window gets crowded.\n- **Citation navigation** now keeps citation labels conservative until page\n  locations are verified, while quote-based citations can jump back to the\n  matching Zotero passage.\n- **MinerU PDF parsing** provides higher-fidelity extraction for tables,\n  equations, figures, and local `mineru-api` servers, with a richer file\n  manager for bulk parsing, cache repair, sync packages, tags, and parsing\n  filters.\n\nThanks to [@jianghao-zhang](https:\u002F\u002Fgithub.com\u002Fjianghao-zhang) and\n[@boltma](https:\u002F\u002Fgithub.com\u002Fboltma) for major contributions to the Codex App\nServer, Claude Code, and file upload workflows.\n\n## Quick Start\n\n1. Download the latest `.xpi` file from the\n   [Releases page](https:\u002F\u002Fgithub.com\u002Fyilewang\u002Fllm-for-zotero\u002Freleases).\n2. In Zotero, open `Tools` -> `Add-ons` -> gear icon ->\n   **Install Add-on From File**, then select the `.xpi`.\n3. Restart Zotero.\n4. Open `Preferences` -> `llm-for-zotero`, choose a provider, enter the base\n   URL, key, and model, then click **Test Connection**.\n5. Open a PDF in Zotero and click the LLM Assistant icon in the right-hand\n   toolbar.\n\nIf you do not want to use a provider API key, start with\n[WebChat](#webchat-setup-chatgpt-web-sync) or\n[Codex App Server](#codex-setup-chatgpt-plus-subscribers).\n\n## Configuration\n\nOpen `Preferences` -> `llm-for-zotero`.\n\n1. Select your **Provider**.\n2. Paste your **API Base URL**, **secret key**, and **model name**.\n3. Click **Test Connection**.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fmodel_setting.gif\" alt=\"Animation showing provider and model configuration\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\nThe plugin supports multiple provider protocols, including `responses_api`,\n`openai_chat_compat`, `anthropic_messages`, and `gemini_native`.\n\nYou can configure multiple providers and models for different tasks, such as a\nmultimodal model for figures and a text model for summaries. The conversation\npanel also supports model-specific reasoning levels and hyperparameters such as\n`temperature` and `max_tokens_output`.\n\n\u003Ca id=\"features\">\u003C\u002Fa>\n\n## Demos\n\n### Grounded Paper Chat\n\nOn the first message, the model loads the current paper as context. Follow-up\nquestions use focused retrieval from the same paper, keeping conversations fast\nand grounded.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fcitation_jump.gif\" alt=\"Animation showing one-click jump from an AI citation to the paper source\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\nClick any generated citation to jump straight to the source passage in Zotero.\n\n### Summaries and Selected Text\n\nSummarize a full paper, focus on methodology or results, or select any paragraph\nand ask the model to explain it.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fsummarize.gif\" alt=\"Animation showing an instant paper summary in the sidebar\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Ftext.gif\" alt=\"Animation showing selected text being explained by the model\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\nThe selected-text pop-up can add highlighted text to chat with one click. It can\nalso be disabled in settings.\n\n### Figures and External Files\n\nTake screenshots of figures, attach up to 10 screenshots, or upload local files\nas additional context. Supported uploads include PDF, DOCX, PPTX, TXT, and Markdown.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fscreenshot.gif\" alt=\"Animation showing screenshot-based figure interpretation\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fupload_files.gif\" alt=\"Animation showing external file upload for additional context\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\n### Multi-Paper Comparison\n\nOpen multiple papers in Zotero tabs and type `\u002F` to cite another paper as\nadditional context.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fmulti.gif\" alt=\"Animation showing cross-paper comparison using the slash command\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\n### Notes, History, and Presets\n\nSave answers or selected text to Zotero notes, export full conversations in\nMarkdown, and customize quick-action presets for repeated research tasks.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fsave_notes.gif\" alt=\"Animation showing model answers being saved to Zotero notes\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fsave_chat.gif\" alt=\"Animation showing conversation export to Zotero notes with markdown\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fshortcuts.gif\" alt=\"Animation showing custom quick-action preset configuration\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\n## File-Based Notes\n\nBeyond Zotero's built-in notes, the agent can save Markdown research notes to\nany local directory you choose. Point it at an\n[Obsidian](https:\u002F\u002Fobsidian.md\u002F) vault, a [Logseq](https:\u002F\u002Flogseq.com\u002F) graph,\nor a plain folder of `.md` files.\n\nOpen `Preferences` -> `llm-for-zotero` and scroll to the **Notes Directory**\nsection.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Foutside_notes.png\" alt=\"Screenshot of the Notes Directory settings panel\" width=\"512\" \u002F>\n\u003C\u002Fp>\n\n| Setting                  | Description                                                          | Example              |\n| ------------------------ | -------------------------------------------------------------------- | -------------------- |\n| **Nickname**             | How you refer to this directory in chat                              | `Obsidian`, `Logseq` |\n| **Notes Directory Path** | Absolute path to the root directory where notes are saved            | `\u002FUsers\u002Fme\u002FMyVault`  |\n| **Default Folder**       | Default subfolder for new notes                                      | `Logs`               |\n| **Attachments Folder**   | Folder for copied figures and images, relative to the directory root | `Logs\u002Fimgs`          |\n\nAsk the agent to write a note using the configured nickname, for example:\n_\"Summarize this paper and save it to Obsidian.\"_ The agent gathers paper\nmetadata, writes a Markdown note, adds YAML frontmatter, optionally copies\nfigures from MinerU-parsed PDFs, and saves the note under the configured folder.\n\nOr if you want to keep notes inside Zotero, the agent can also write to internal item notes with the `write-note` skill. Just ask it to \"save a note for this paper\" without mentioning an external directory.\n\n### Zotero Notes vs. File-Based Notes (both generated by the plugin)\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fnote2.jpeg\" alt=\"Zotero internal note\" width=\"512\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fobsidian_example.png\" alt=\"Example of a paper note rendered in Obsidian\" width=\"512\" \u002F>\n\u003C\u002Fp>\n\nNotes use [Pandoc citation syntax](https:\u002F\u002Fpandoc.org\u002FMANUAL.html#citations)\nsuch as `[@citekey]`, which works with Obsidian Zotero Integration, Pandoc\nplugins, and many Markdown readers.\n\n> Note templates and figure-embedding rules live in the `write-note` skill.\n> Open the **Standalone Window** -> **Skills** portal to edit them.\n\n## Agent Mode (beta)\n\nAgent Mode is disabled by default. Enable it in `Preferences`, then toggle\n`Agent (beta)` in the context bar.\n\nIt can read and search your library, draft notes, update metadata or tags with\nconfirmation, and undo recent write actions in the same session.\n\nWhen enabled, the LLM can act on your Zotero library with read tools, write\ntools, confirmation cards, and session undo.\n\nLong agent runs are cache-aware. The plugin keeps stable Zotero context and\npreviously read evidence separate from the changing chat transcript, tracks which\npapers and passages have already been inspected, and automatically compacts old\nturns when the model context fills up. This lets follow-up questions reuse\ngrounded evidence when it is still relevant, while still asking the agent to read\nagain when the needed source or coverage layer is missing.\n\n| Tool area                | Examples                                                                                                                                          |\n| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Library and PDF reading  | Search items and collections, read metadata, read papers, search paper passages, render PDF pages, inspect attachments                            |\n| Scholarly discovery      | Search CrossRef and Semantic Scholar for metadata, recommendations, references, and citations                                                     |\n| Library writes           | Apply tags, update metadata, move items, manage collections, manage attachments, merge duplicates, trash items, import identifiers or local files |\n| Notes                    | Edit the active Zotero note or create a new note in plain text, Markdown, or HTML                                                                 |\n| Filesystem and scripting | Read\u002Fwrite allowed local files, run analysis commands, or execute Zotero JavaScript with write confirmations                                      |\n| Safety                   | Undo the most recent write action in the conversation, with the last 10 entries kept per session                                                  |\n\nThe design philosophy is simple: read tools are unrestricted; write tools stay\nreviewable and undoable.\n\n### Agent Mode Demos\n\n#### Multi-step workflow\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fagent\u002Fmulti_steps.gif\" alt=\"Animation showing multi-step agent workflow\" width=\"512\" \u002F>\n\u003C\u002Fp>\n\n#### Find related papers\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fagent\u002Frelated_papers.gif\" alt=\"Animation showing agent finding related papers in the library\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\n#### Apply tags\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fagent\u002Fapply_tags.gif\" alt=\"Animation showing agent applying tags to a paper\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\n#### Write a note\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fagent\u002Fwrite_note.png\" alt=\"Screenshot showing agent writing a note for a paper\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\n## Skills\n\nSkills customize Agent Mode behavior for recurring research workflows such as\npaper QA, evidence retrieval, figure analysis, paper comparison, literature\nreviews, note writing, and cited-reference import.\n\n\u003Cdetails>\n\u003Csummary>Built-in skills and custom skill setup\u003C\u002Fsummary>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fskills.png\" alt=\"Screenshot of the Skills management portal\" width=\"512\" \u002F>\n\u003C\u002Fp>\n\nSkills are customizable guidance files that shape how Agent Mode approaches\ndifferent types of requests. When your message matches a skill's trigger\npatterns, the skill's instructions are injected into the agent prompt.\n\n> Skills require **Agent Mode**. They have no effect in standard chat mode.\n\nBuilt-in skills:\n\n| Skill                    | What it guides the agent to do                                      |\n| ------------------------ | ------------------------------------------------------------------- |\n| `simple-paper-qa`        | Answer general questions about a paper efficiently                  |\n| `evidence-based-qa`      | Find specific methods, results, or evidence with targeted retrieval |\n| `analyze-figures`        | Interpret figures and tables using MinerU-extracted images          |\n| `compare-papers`         | Compare multiple papers using batched reads and focused retrieval   |\n| `library-analysis`       | Summarize or analyze your entire library without context overflow   |\n| `literature-review`      | Conduct a structured literature review                              |\n| `write-note`             | Write Zotero notes or Markdown notes in configured local folders    |\n| `import-cited-reference` | Import papers cited in the current PDF into Zotero                  |\n\nTo create a custom skill, open the **Standalone Window**, click the **Skills**\nicon, choose **\"+ New skill\"**, edit the skill file, and save. Skills are stored\nas Markdown files in `{ZoteroDataDir}\u002Fllm-for-zotero\u002Fskills\u002F`.\n\n\u003C\u002Fdetails>\n\n## Codex Setup (ChatGPT Plus Subscribers)\n\nIf you have a ChatGPT Plus subscription, you can use Codex models in the plugin\nwithout a separate API key by signing in through the Codex CLI.\n\nNew users should choose **Codex App Server** from the **Agent** tab. The older\n**Codex Auth (Legacy)** path remains available for existing users, but is\nplanned for future deprecation after app-server validation.\n\n\u003Cdetails>\n\u003Csummary>Codex App Server setup and legacy Codex Auth\u003C\u002Fsummary>\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fcodex_claude.png\" alt=\"Screenshot showing recommended Codex App Server configuration in plugin settings\" width=\"512\" \u002F>\n\u003C\u002Fp>\n\n### Codex App Server setup\n\n1. Install the Codex CLI:\n\n   ```bash\n   npm install -g @openai\u002Fcodex\n   ```\n\n   On macOS, you can also use `brew install --cask codex`. On Windows, install\n   Codex from PowerShell or Command Prompt rather than WSL, so Zotero MCP can\n   use the Windows-local loopback connection.\n\n2. Log in:\n\n   ```bash\n   codex login\n   ```\n\n   Credentials are saved to `~\u002F.codex\u002Fauth.json`.\n\n3. In Zotero, open `Preferences` -> `llm-for-zotero` -> **Agent** tab.\n4. Turn on **Enable Codex App Server integration**.\n5. Choose the default model and reasoning level.\n6. Click **Test connection**.\n7. In the chat header, click **Codex** to switch into the Codex conversation\n   system.\n\n`Codex App Server` and `Claude Code` are mutually exclusive runtime modes in the\nAgent tab. Disable one before enabling the other.\n\n### Codex Auth (Legacy)\n\nExisting users can keep the legacy direct backend configuration:\n\n- Open the **AI Providers** tab.\n- Choose **Auth Mode** -> `Codex Auth (Legacy)`.\n- Keep API URL `https:\u002F\u002Fchatgpt.com\u002Fbackend-api\u002Fcodex\u002Fresponses`.\n- Keep your Codex model name, for example `gpt-5.5`.\n\nLegacy notes:\n\n- Reads credentials from `~\u002F.codex\u002Fauth.json` or `$CODEX_HOME\u002Fauth.json`.\n- Automatically attempts token refresh on 401 responses.\n- Embeddings are not supported in this legacy direct mode yet.\n- Local PDF\u002Freference text grounding and screenshot\u002Fimage inputs are supported.\n- The Responses `\u002Ffiles` upload plus `file_id` attachment flow is not supported\n  yet.\n\n\u003C\u002Fdetails>\n\n## Claude Code Setup (Experimental)\n\nClaude Code mode runs Claude Code as a separate conversation system inside\nZotero. It reuses the sidebar and standalone-window UI, but has separate\nconversation history, scope state, model settings, permission semantics, slash\ncommands, and project skills.\n\n> Claude Code mode currently does **not** support native Zotero API operations.\n> Use built-in [Agent Mode](#agent-mode-beta) for native library tools such as\n> reading item state, editing notes, tagging papers, updating metadata, or\n> importing items.\n\n\u003Cdetails>\n\u003Csummary>Claude Code prerequisites, bridge setup, and project assets\u003C\u002Fsummary>\n\nPrerequisites:\n\n- A working Claude Code CLI installation. Follow Anthropic's official\n  [Claude Code installation](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Finstallation.md),\n  [quickstart](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fquickstart.md), and\n  [authentication](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fauthentication.md) docs.\n- The `claude` command must be on `PATH` and authenticated.\n- Node.js and npm for the companion bridge adapter.\n\n### 1. Install and verify Claude Code\n\nRun:\n\n```bash\nclaude\n```\n\nComplete any login or authentication prompts before continuing.\n\n### 2. Start the Zotero Claude bridge\n\nClaude Code mode depends on the companion bridge repo\n[`cc-llm4zotero-adapter`](https:\u002F\u002Fgithub.com\u002Fjianghao-zhang\u002Fcc-llm4zotero-adapter).\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fjianghao-zhang\u002Fcc-llm4zotero-adapter.git\ncd cc-llm4zotero-adapter\nnpm install\nnpm run build\nnpm run serve:bridge\n```\n\nCheck that the bridge is alive:\n\n```bash\ncurl -fsS http:\u002F\u002F127.0.0.1:19787\u002Fhealthz\n```\n\nFor macOS background use, install the LaunchAgent from the adapter repo:\n\n```bash\n.\u002Fscripts\u002Finstall-macos-daemon.sh\n```\n\nUseful bridge daemon commands:\n\n```bash\nnpm run daemon:status\nnpm run daemon:start\nnpm run daemon:stop\nnpm run daemon:restart\nnpm run daemon:uninstall\n```\n\nIf Claude Code mode stops responding, restart the bridge and re-check\n`\u002Fhealthz`. A passing `\u002Fhealthz` check only proves that the adapter is running;\nit does not prove that the underlying `claude` CLI is installed, authenticated,\nor correctly configured.\n\n### 3. Enable Claude Code inside Zotero\n\nOpen `Preferences` -> `llm-for-zotero` -> **Agent** tab.\n\n| Setting                            | Recommended value                  |\n| ---------------------------------- | ---------------------------------- |\n| **Enable Claude Code integration** | `On`                               |\n| **Bridge URL**                     | `http:\u002F\u002F127.0.0.1:19787`           |\n| **Claude Config Source**           | `default - user + project + local` |\n| **Permission Mode**                | `safe`                             |\n| **Default Model**                  | `sonnet`                           |\n| **Default Reasoning**              | `auto`                             |\n\nKeep **Claude Config Source** on `default` unless you already understand Claude\nCode settings layers. In `default`, Claude Code can use your normal user\nsettings plus Zotero-managed project and per-conversation local settings.\nThe other options are:\n\n- `user-only`: only your machine-wide Claude settings.\n- `zotero-only`: only Zotero-managed project and local settings.\n\nAfter enabling the integration, click the **Claude Code** button in the chat\nheader to enter Claude Code mode.\n\n### 4. Prepare Claude project skills and commands\n\nZotero creates a Claude runtime root under your home directory, usually shaped\nlike:\n\n```text\n~\u002FZotero\u002Fagent-runtime\u002Fprofile-...\u002F\n```\n\nShared Claude project assets live in:\n\n```text\nCLAUDE.md\n.claude\u002Fsettings.json\n.claude\u002Fskills\u002F\n.claude\u002Fcommands\u002F\n```\n\nEach Claude conversation also gets its own local `.claude` folder under the\nruntime `scopes\u002F` tree, so per-conversation overrides do not leak into other\nchats.\n\nThe Zotero UI exposes `opus`, `sonnet`, and `haiku` as capability tiers. If you\nroute Claude Code through a compatible provider layer or proxy, configure that\nin Claude Code itself; Zotero only selects the tier and forwards the request to\nthe bridge.\n\n\u003C\u002Fdetails>\n\n## MinerU PDF Parsing\n\n**MinerU** is an advanced PDF parsing engine that extracts high-fidelity\nMarkdown from PDFs, preserving tables, equations, figures, and complex layouts\nthat standard text extraction often mangles.\n\nWhen enabled, the plugin sends newly added PDF attachments to MinerU for parsing\nand caches the result locally. Later interactions with that paper use the\nMinerU-parsed content.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002FminerU.png\" alt=\"Screenshot showing MinerU PDF parsing results in the plugin\" width=\"512\" \u002F>\n\u003C\u002Fp>\n\n### How to enable MinerU\n\n1. Open `Preferences` -> `llm-for-zotero`.\n2. Find the **MinerU** section and check **Enable MinerU**.\n3. Keep cloud mode enabled, or check **Use local MinerU server** for local mode.\n4. For cloud mode, optionally enter your own MinerU API key — see below.\n5. For local mode, run a self-hosted `mineru-api` server and keep the default\n   base URL (`http:\u002F\u002F127.0.0.1:8000`) unless your server uses a different\n   address.\n6. Add or import a PDF into your Zotero library. The plugin will automatically\n   parse newly added PDF attachments with MinerU and cache the result for future conversations.\n\nMinerU can start without an API key through the built-in API, but a personal key\nis strongly recommended. The built-in API may no longer be supported after\nJune 1, 2026.\n\nTo get a free personal key:\n\n1. Go to [mineru.net](https:\u002F\u002Fmineru.net) and create an account.\n2. Navigate to account settings and generate an API key.\n3. In Zotero, paste the key into the **MinerU** section.\n4. Click **Test Connection**.\n\nWhen a personal key is provided, the plugin calls\n`https:\u002F\u002Fmineru.net\u002Fapi\u002Fv4` directly.\n\n### Using a local MinerU server\n\nLocal MinerU server support was contributed by\n[@renyong18](https:\u002F\u002Fgithub.com\u002Frenyong18) in\n[PR #152](https:\u002F\u002Fgithub.com\u002Fyilewang\u002Fllm-for-zotero\u002Fpull\u002F152).\n\nLocal mode sends PDFs to a self-hosted `mineru-api` server through\n`POST \u002Ffile_parse` and stores the returned ZIP output in the same local cache\nformat as cloud parsing. The default base URL is `http:\u002F\u002F127.0.0.1:8000`.\n\n**Prerequisites for local mode**:\n\n1. Install MinerU and run `mineru-api` (see the\n   [MinerU docs](https:\u002F\u002Fgithub.com\u002Fopendatalab\u002FMinerU) for installation).\n2. Make sure required models are downloaded — `mineru-api` lazy-loads on first\n   request, so the very first parse (or the first parse after switching backend)\n   can take noticeably longer than steady state.\n\nYou can pick a `Backend` in the local section:\n\n- `pipeline` (default) — general-purpose, multi-language, CPU-friendly.\n- `vlm` — VLM-based, high accuracy on Chinese\u002FEnglish documents, requires GPU.\n- `hybrid` — newer high-accuracy hybrid pipeline, multi-language, requires\n  local compute.\n\nThe first parse after starting the local server, or after changing backend, can\nbe slow while MinerU loads or downloads models. `Test Connection` checks that\nthe server process responds at `\u002Fhealth`; it does not guarantee that all models\nare warmed up.\n\nWith the default `127.0.0.1` address, PDFs stay on your machine. If you change\nthe base URL to a LAN or remote server, PDFs are sent to that server.\n\n**Pause \u002F cancel limitation**: `mineru-api` exposes no cancel or DELETE endpoint\n(only `POST \u002Ffile_parse`, `POST \u002Ftasks`, `GET \u002Ftasks\u002F{id}`,\n`GET \u002Ftasks\u002F{id}\u002Fresult`, `GET \u002Fhealth`). When you click Pause, the plugin stops\nthe queue and aborts the HTTP wait, but the parse already running on the server\nkeeps executing until it finishes — the GPU\u002FCPU will not free up sooner. If you\nneed to abort immediately (for example to switch backend without waiting),\nrestart the `mineru-api` process yourself.\n\n### Managing MinerU caches\n\nThe **MinerU** preferences tab includes a **Manage Files** panel for maintaining\nparsed PDF caches:\n\n- Browse cached and uncached PDFs by collection, tag, title, author, year, and\n  added date.\n- Start parsing all visible files, only filtered files, or selected files.\n- Repair local MinerU caches and synced packages when metadata or files drift.\n- Delete all, filtered, selected, or single-item caches from the manager.\n- Use tag filters, including automatic Zotero tags, to choose which papers are\n  included in bulk actions.\n\nAdvanced parsing filters can skip files before automatic or bulk parsing:\n\n- **Skip files over N pages** controls the maximum page count used by Start All,\n  Start Filtered, Start Selected, and auto-parse. The default is 100 pages.\n- **Exclude PDFs by Filename** accepts comma-separated substrings, or regex\n  patterns wrapped in `\u002Fslashes\u002F`, for translated copies, supplements, or other\n  files you do not want parsed automatically.\n\nIf **Sync MinerU cache with Zotero file sync** is enabled, the plugin can create\ncompanion ZIP attachments containing `full.md`, `manifest.json`,\n`content_list.json`, and extracted assets. Existing local caches sync only when\nyou request it from the MinerU tab, and synced packages can restore a missing\nlocal cache when needed.\n\n\u003Ca id=\"webchat-setup-chatgpt-web-sync\">\u003C\u002Fa>\n\n## WebChat Setup (ChatGPT & Deepseek Web Sync)\n\nWebChat mode sends questions to [chatgpt.com](https:\u002F\u002Fchatgpt.com) and [deepseek.com](https:\u002F\u002Fchat.deepseek.com) through a\nbrowser extension, then streams responses back into Zotero. It is useful when\nyou want ChatGPT\u002Fdeepseek web access without a provider API key.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\".\u002Fassets\u002Fwebchat.gif\" alt=\"Screenshot of WebChat mode connected to chatgpt.com\" width=\"1024\" \u002F>\n\u003C\u002Fp>\n\nPrerequisites:\n\n- A ChatGPT account for `chatgpt.com` WebChat or a Deepseek account for `deepseek.com` WebChat.\n- A Chromium-based browser such as Chrome.\n\nSetup:\n\n1. Download the latest `extension.zip` from\n   [sync-for-zotero releases](https:\u002F\u002Fgithub.com\u002Fyilewang\u002Fsync-for-zotero).\n2. Unzip it.\n3. Open `chrome:\u002F\u002Fextensions`, enable **Developer Mode**, choose\n   **Load unpacked**, and select the unzipped extension folder.\n4. In Zotero, open `Preferences` -> `llm-for-zotero` and set\n   **Auth Mode** -> `WebChat`.\n5. ⚠️: Keep a ChatGPT tab open in your browser. A green dot in Zotero means the extension and ChatGPT tab are connected. Make sure the tab and Zotero stay in the same monitor. No minimization or backgrounding, or the connection may drop.\n\n## Privacy and Data Flow\n\nData flow depends on the backend you choose. Local models and local MinerU can\nkeep processing on your machine; cloud providers, WebChat, Claude Code, Codex,\nand cloud MinerU involve their respective services or companion runtimes.\n\n\u003Cdetails>\n\u003Csummary>Detailed backend data flow\u003C\u002Fsummary>\n\n- In standard provider mode, paper content and user messages are sent to the\n  model provider you configure.\n- In local-model mode, requests go to the local OpenAI-compatible endpoint you\n  configure.\n- In WebChat mode, requests are relayed through the browser extension to\n  `chatgpt.com` or `chat.deepseek.com`.\n- In cloud MinerU mode, newly added PDFs are sent to MinerU for parsing when\n  parsing is enabled.\n- In local MinerU mode, newly added PDFs are sent to the local or remote\n  `mineru-api` server you configure.\n- Conversation history and cached paper context are stored locally by the\n  plugin.\n- Agent Mode write operations are routed through reviewable actions and session\n  undo where supported.\n\n\u003C\u002Fdetails>\n\n## Roadmap\n\n- [x] Agent mode (beta)\n- [x] MinerU PDF parsing\n- [x] GitHub Copilot auth\n- [x] WebChat mode (ChatGPT web sync)\n- [x] Standalone window mode\n- [x] File-based notes (Obsidian, Logseq, any Markdown directory)\n- [x] Claude Code integration\n- [x] Codex App Server integration\n- [x] Local MinerU support\n- [x] Customized skills\n- [x] Cross-device synchronization (MinerU cache)\n- [ ] Agent memory system\n\n## FAQ\n\n> **Q: Does it require an API key to use this plugin?**\n>\n> A: It depends on the backend you choose. The plugin supports multiple backends with different requirements:\n\n| Goal                                                        | Recommended path                                                              | API key required?               |\n| ----------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------- |\n| Use OpenAI, Gemini, DeepSeek, Moonshot, or another provider | Configure an API provider in Zotero preferences                               | Yes                             |\n| Use a local model                                           | Connect any OpenAI-compatible local HTTP API                                  | Usually no                      |\n| Use ChatGPT in the browser                                  | [WebChat](#webchat-setup-chatgpt-web-sync) with the Sync for Zotero extension | No                              |\n| Use Codex models with ChatGPT Plus                          | [Codex App Server](#codex-setup-chatgpt-plus-subscribers)                     | No separate API key             |\n| Use Claude Code inside Zotero                               | [Claude Code bridge](#claude-code-setup-experimental)                         | Claude Code auth                |\n| Improve PDF extraction for tables, equations, and figures   | [MinerU PDF parsing](#mineru-pdf-parsing)                                     | Personal MinerU key recommended |\n\n> **Q: Is it free to use?**\n>\n> Yes, the plugin is free. You only pay for API calls if you choose a paid\n> provider. With Codex App Server, ChatGPT Plus subscribers can use Codex models\n> without a separate API key. If you find this helpful, consider leaving a star\n> on GitHub or [buying me a coffee](https:\u002F\u002Fbuymeacoffee.com\u002Fyat.lok).\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F1e945e57-4b99-4d25-b8d5-fb120e100b62\" width=\"200\" alt=\"Alipay donation QR code\">\n\u003C\u002Fp>\n\n> **Q: Is my data used to train models?**\n>\n> The plugin does not train models. Data handling depends on the backend you\n> choose: your configured API provider, local model, WebChat, Codex, Claude\n> Code, or MinerU.\n\n> **Q: How do I report a bug or ask a question?**\n>\n> Please [open an issue](https:\u002F\u002Fgithub.com\u002Fyilewang\u002Fllm-for-zotero\u002Fissues) on\n> GitHub.\n\n## Contributing\n\nContributions are welcome. Bug reports, feature requests, documentation\nimprovements, and pull requests are all useful. Please\n[open an issue](https:\u002F\u002Fgithub.com\u002Fyilewang\u002Fllm-for-zotero\u002Fissues) or submit a\nPR.\n\n## Star History\n\n[![Star History Chart](https:\u002F\u002Fapi.star-history.com\u002Fimage?repos=yilewang\u002Fllm-for-zotero&type=date&legend=top-left)](https:\u002F\u002Fwww.star-history.com\u002F?repos=yilewang%2Fllm-for-zotero&type=date&legend=top-left)\n","llm-for-zotero 是一个基于 Zotero 个人文献库的研究助手系统。它利用大型语言模型（LLM）技术，使用户能够在不离开Zotero的情况下对文献进行提问、总结、图表检查、来源对比以及笔记保存等操作。该项目支持多种API供应商及本地OpenAI兼容模型，并集成了WebChat、Codex App-Server和Claude Code等功能。非常适合需要高效管理和分析大量学术资料的研究人员或学生使用。通过这个插件，可以极大提高文献阅读与研究工作的效率。",2,"2026-06-11 03:51:52","high_star"]