firekern/zusia
firekern/zusia has 30 GitHub stars and 4 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 23:33 UTC. Last push 2026-11-14.
Measured star growth
- in 24h
- 0
- in 7 days
- Collecting history
- in 15 days
- Collecting history
- in 1 month
- Collecting history
Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.
About
Zusia, a study buddy inside Zotero: ask Claude Code, Codex or Antigravity about the paper you are reading. LaTeX, drawings, theorem links, glass UI.
AIREADME.md
Original
Zusia
Your study buddy inside Zotero.
Ask about the paper you're reading. Get maths, drawings and proofs back.
TL;DR
- 💬 A chat next to the PDF that reads the whole paper, in its own panel at the side of the window.
- ✏️ Answers with LaTeX, drawings and numbered theorem boxes.
- 🔑 Uses Claude Code, Codex or Antigravity with your own login. No API keys.
- ⏱️ Install in 2 minutes: jump to Install.
1. Ask about the paper
Open a paper and ask. Zusia is the panel on the right of the window, beside your library and the PDF. It follows the paper you select or open; drag its edge to resize it, and ⌥Z (Alt+Z) hides it and brings it back. Turn on Drawing and LaTeX for a diagram and real maths.
Recorded in a real Zotero on a Mac: Attention Is All You Need, a live answer from Claude. 22 seconds, with the wait sped up.

2. Make it yours
Settings → Zusia → Appearance → Layout. Four ways to see the chat. Minimal: the conversation and the message box. Standard: the tools as icons, one click away. Rich: a card for the paper with your reading progress, the tools by name. Visual: your buddy beside each answer, bubbles, prompt cards and colour. The setup wizard asks on first run.

Then everything else in Settings → Zusia. Style, buddy, pattern, accent colour, background image and button labels, all updating live in the chat. Glass, corners, font, answer length, level, tone and the system prompt are there too.

Eight accents. Red on black is the one in every video here.
3. Follow a proof
Turn on LaTeX. Definitions, lemmas and theorems come back as numbered boxes, and every
\refis a link: click to jump, Back (⌥←) to return.

4. Didn't click? Ask again, better
One button under every answer. It comes back with the intuition first, then the steps, an example and the usual trap.

5. Ask about a figure
📎 → Current PDF page. The page you are looking at goes with the question, so figures and tables can be asked about. Upload, paste, drop or screenshot work too.

Everything else, in one line each
| Feature | How | |
|---|---|---|
| 🔴 | Explain a passage | Select text in the PDF → Explain this |
| 🟠 | Ask about a passage | Select text → Ask your assistant about this, then add your question |
| 🩷 | Clarifications | Every Ask and Explain is saved: highlighter icon → passage, prompt, answer |
| 🟣 | Notes | Save any answer or drawing as a Zotero note under the paper |
| 🔵 | Search | 🔍 searches the chats of every paper |
| 🟢 | Models | Pick assistant, model and reasoning effort from the message box |
| 🟤 | Memory | /remember a note, /forget one; click the paper chip above the message box to see, edit or reset what Zusia keeps |
| 🟡 | Printed pages | Ask about "page 18" and the assistant reads the page printed 18, whatever its PDF number |
| ⚫ | Setup | A visual wizard on first run, including the assistant's voice: a preset or your own system prompt |
| ⚪ | Side panel | ⌥Z / Alt+Z shows and hides it; drag its edge to resize, double-click the edge to reset; put it on the left, the right or in the item pane in Settings |
Install
- Install one assistant CLI and sign in: Claude Code, Codex or Antigravity (
agy). - Download
zusia.xpifrom the latest release. - In Zotero: Tools → Plugins → ⚙ → Install Plugin From File… → pick the
.xpi. Restart if asked. - Open a paper. Zusia appears in a panel on the right and starts the setup wizard. To have it on the left or in Zotero's item pane instead, choose Settings → Zusia → Chat → Where the chat is.
Updates arrive on their own after that: Zotero checks the release feed.
What the assistant reads
- 📄 The paper's full text, as Zotero extracts it from the PDF (split by page), EPUB or web snapshot. Answers cite pages as (p. N).
- 🎯 Where you are. The page on screen and the passage you selected come first, with the pages you have turned to so far. Antigravity, which cannot read files, gets the pages that fit, chosen around that page and the question, and can ask for a few more.
- 🗺️ A reading map: the printed page labels, the outline with page ranges, and where each equation, figure and table is. A book is split into section files, whatever its length.
- 🧠 What it remembers about this paper: what you understood, what is still unclear, how you like answers, your
/remembernotes and a running summary. Every few questions a short call to a cheap model (Claude Haiku, or Antigravity) brings it up to date. - 🏷️ Metadata and your annotations: title, authors, abstract, highlights and comments.
- 🚫 No text, no guessing. For a scanned PDF with no text layer, the assistant says it cannot read the paper instead of answering from the abstract.
Privacy
- 🖥️ The assistants run on your computer with your own login. Zusia has no server and needs no API keys.
- 📄 They get the paper's full text, metadata and your annotations, its reading map, your reading progress and its memory, plus any image you attach. The CLI sends them to its provider (Anthropic, OpenAI or Google), as it does with anything you type into it.
- 🔕 To send only the metadata, abstract and annotations, turn off Settings → Zusia → Chat → Send the paper's full text. Track reading progress in the same card stops noting the pages you turn to.
- 🧠 Keeping the memory takes extra calls to the same CLI, in the background. Turn them off in the Memory sheet (click the paper chip). Antigravity stores each of these calls in your
agyconversation history. - 📁 Chats, clarifications, images, the reading map, your reading progress and the memory stay in
zusia/inside Zotero's data folder.
For developers: build, test, release, record the videos
Build
npm ci
npm run build # writes zusia.xpi
Test
npm test # unit tests (jsdom): rendering, settings, wizard, backends, repo checks
npm run shots # screenshots of the UI in headless Firefox (optional)
npm run test:zotero # the checks inside a real, headless Zotero (macOS app, or Flatpak on Linux)
npm run test:zotero:linux # the same in Docker, against the official Linux build
npm run test:zotero:windows # the same in the Windows build under Wine, in Docker
ZUSIA_BACKGROUND=path/to/illustration.jpg npm run videos # re-records the README videos (macOS)
INSIDE=1 ZUSIA_BACKGROUND=path/to/illustration.jpg npm run videos # the same, filmed from inside Zotero: no permissions
REHEARSE=1 ZUSIA_BACKGROUND=path/to/illustration.jpg npm run videos # walks the same scenes without recording
The videos are recorded in a real Zotero with its own demo profile and library, so your library is never used. The scenes move the real pointer: don't touch the Mac while they run. Needs ffmpeg, cliclick, the claude CLI, and Screen Recording and Accessibility permission for the app the terminal runs in. With INSIDE=1 neither permission is needed, nor cliclick: Zotero draws its own window into every frame, clicks and typing reach it as events, and the pointer and the window's buttons are drawn into the film afterwards, so the Mac's pointer stays yours; keep the demo window uncovered while it runs. The videos on this page were made this way. With REHEARSE=1 nothing is recorded, the pointer stays where it is and no assistant is called, so neither permission is needed: every scene is walked through with events sent to Zotero and a canned answer, and what the window shows at each step is saved under ~/.cache/zusia-demo/rehearsal/. Run it after the interface changes, to see that the scenes still find their way.
Release
Bump version in package.json and src/manifest.json, then tag it:
git tag v1.1.0 && git push origin v1.1.0
The tag is what releases. .github/workflows/release.yml refuses to run if the tag and the two versions disagree, then runs the tests, builds the .xpi, writes updates.json and attaches both to a GitHub release. Pushing to main never publishes anything.
New behaviour starts with a failing test; see CONTRIBUTING.md.
Credits
Icons: Phosphor Icons (MIT). Maths: KaTeX (MIT) and Latin Modern Math (GUST Font License). The study buddies are original to this project; the illustrations were made for Zusia with Google Gemini. Papers in the videos: arXiv 1706.03762, 1512.03385, 1810.04805, 2010.11929, 2005.14165, 1412.6980. Details in THIRD_PARTY_NOTICES.md.
Zusia is MIT licensed. See LICENSE.