Sub-Sub
Your research assistant, working from your own Zotero library.
Sub-Sub reads what you already have, finds what you are missing in PubMed, Europe PMC and OpenAlex, and writes notes in Markdown. It also keeps the library in order: it imports, tags and repairs references, and shows you each change before it happens. It runs on your computer, in the browser or in the terminal. It is built on the pi agent and talks to Zotero through Zotero's local API.
Website and guide: https://subsub.tiagojacinto.eu
"This mere painstaking burrower and grub-worm of a poor devil of a Sub-Sub appears to have gone through the long Vaticans and street-stalls of the earth, picking up whatever random allusions to whales he could anyways find in any book whatsoever." Herman Melville, Moby-Dick (1851), the Extracts
What it does
Sub-Sub has two modes.
- The Researcher (the default) reads items in your library, searches PubMed, Europe PMC and OpenAlex in one merged search, finds gaps, checks the citations in a manuscript, and writes notes in your Sub-Sub folder. It also does everything the Librarian does, so you can find papers and import and tag them in the same conversation.
- The Librarian only manages the library: it tags items, imports by DOI, PMID or ISBN, repairs metadata, finds duplicates, attaches open-access PDFs and checks retractions. It has no search tools. Give it a fast, cheap model for long tagging sessions.
Each mode can have its own model. Switch with /researcher and /librarian, or with the buttons in the browser view.
Every library change works the same way in both modes:
- The Zotero server computes the change first. Sub-Sub shows it to you (the tags it adds and the tags it removes) and applies it only when you select Yes. The check is in the program, so the model cannot skip it.
- If you edit an item in Zotero while the preview is open, Sub-Sub shows you the new preview before it changes anything. Each change also sends the item's version, so a field you edit at the moment of writing is not overwritten.
- Every change is journaled, including new collections.
/undoreverts the last one, and the browser view shows an Undo button under each change. - Nothing is deleted: items go to the Zotero trash. Only tags from your tag list can be added.
What Sub-Sub writes
Sub-Sub writes literature notes, syntheses and reviews from what it read, with a source for every claim. It drafts text for your manuscript or thesis only when you ask, and marks the drafted text so that you can check it. It does not draft text for assignments, even when you ask.
To learn to read papers yourself, use /read: Sub-Sub finds the passages and asks questions, and you write the answers. /lit reading list: <topic> gives a reading list with questions to read with, and no results.
The Commands page lists the tools and commands of each mode.
Requirements
- Zotero 10 or later, running, with Settings > Advanced > "Allow other applications on this computer to communicate with Zotero" on.
- Node.js 22.19 or later, and uv. The installers add both if they are missing.
- An account with a model provider that pi supports (for example OpenCode Go, OpenRouter, Anthropic, OpenAI, Mistral, Google), or a local model. To try Sub-Sub without paying, a free Google AI Studio key is enough (see Use Sub-Sub for free).
- macOS, Linux or Windows.
Install
macOS and Linux:
curl -fsSL https://subsub.tiagojacinto.eu/install.sh | sh
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://subsub.tiagojacinto.eu/install.ps1 | iex"
The installers put everything in your user folder (~/.subsub), run subsub init, and add a Sub-Sub shortcut. You do not need administrator rights.
With npm:
npm install -g @tiagojct/subsub
subsub init
subsub doctor
subsub init asks a few questions. Press Enter to accept the default. It creates the Sub-Sub folder (~/Documents/Sub-Sub, or a Sub-Sub folder inside your Obsidian vault) with Inbox/, Literature/, Syntheses/, Research/ and Zotero/, a starter tag list (Zotero/Zotero tags.md) and the note formats (Zotero/Zotero agent.md). subsub doctor checks the set-up; each line marked FIX says what to do.
If you already use pi, you can add Sub-Sub to it: pi install npm:@tiagojct/subsub.
Sub-Sub runs its Zotero server, zotero-local-mcp, from PyPI with uv.
Use
subsub web # in the browser
subsub # in the terminal
subsub --librarian # in the terminal, in the Librarian
subsub tui # on the whole terminal (full screen)
subsub -c # continue the last conversation
subsub --help # all commands
In the browser view, connect a model provider with the model button. In the terminal, type /login.
The terminal has its own look, drawn like the website: a footer with the mode, the library, the model, the context in use and the cost; Sub-Sub's tools in plain words (search the library: asthma); and an approval screen for library changes (y applies, n or Esc leaves the library as it is, Enter does nothing). /notes, /library and /actions open screens for your notes, a library search and the actions of the browser view; F2, F3, F4 and F5 (mode) are shortcuts; so are Alt+N, Alt+L, Alt+A and Alt+M where your terminal sends Alt (in macOS Terminal and iTerm2, Option types a symbol unless you turn on "Use Option as Meta key", and a Mac needs Fn with the F key unless the F keys are set as standard). Nothing is red: a failure is ink with a hollow mark and a word, and a removal is struck through. For terminals that cannot draw box glyphs, set SUBSUB_ASCII=1; SUBSUB_REDUCE_MOTION=1 stops the working indicator from moving; "look": false in the settings brings back the plain screen.
subsub tui puts Sub-Sub on the whole terminal, as the browser view puts it in the browser: a conversation that scrolls, a side panel from 110 columns, the editor and the footer, with the same colours and screens. Besides the commands above, /sessions and /new change the conversation, /model chooses the model, /restart starts pi again in the same conversation, and /quit leaves (Ctrl+C twice also quits). --light or --dark set the colours when your terminal does not say. It does not have pi's own screens (/login, /settings, /tree, /resume): use subsub or subsub web for them.
The browser view also has a library search (each result can start /read or /lit-note), a notes pane that shows the notes of your Sub-Sub folder next to the conversation (note paths and [[links]] in replies open there), argument hints for the commands, and rename, delete (to ~/.subsub/trash) and export for conversations.
Commands in Sub-Sub:
The library commands work in both modes; the research commands need the Researcher.
To check or apply a tag review note from Inbox/ outside Sub-Sub:
subsub review preview 13-31
subsub review apply 13-31
Settings
subsub init writes ~/.config/subsub/config.json (or the file in $SUBSUB_CONFIG). You can also edit it.
The settings of the Zotero server (Sub-Sub folder, tag list, alerts file, contact email) are in ~/.config/zotero-local-mcp/env.
Privacy
Your library stays in Zotero; Sub-Sub uses Zotero's local API and never your zotero.org account. The model provider you choose receives your messages and what the tools return (titles, abstracts, tags, and passages of full texts when you ask for them). PubMed, Europe PMC, OpenAlex, Crossref, Unpaywall and Open Library receive identifiers and search terms, with your contact email if you gave one. Sub-Sub sends no usage data. The browser view listens only on 127.0.0.1 and needs the random key in the address that subsub web opens. Details: https://subsub.tiagojacinto.eu/privacy/
Papers that are not open access
Sub-Sub finds open-access copies through Unpaywall and Europe PMC. For other papers, use Sub-Sub on your institution's network, where the DOI link opens the publisher's version through the library's subscriptions, or use /request-copy. Sub-Sub does not use unlicensed sources.
Reference checks (Starbuck)
Starbuck is an optional add-on. It checks that each cited work exists, that its title, first author and year match the citation, and that it was not retracted or corrected. On request, it also checks whether the source supports the sentence that cites it; Sub-Sub's model judges, and Starbuck checks that every quoted passage is in the source.
Turn it on in subsub init, with the switch in the browser view, or with "addons": ["starbuck"] in the settings. Then subsub doctor must show Starbuck ok. Starbuck writes its report in a _starbuck folder next to the manuscript.
Model test
subsub-bench runs several models on the same tasks against your own library and scores them. Nothing in the library changes. See docs/model-test.md and the Models page for the latest results.
Development
git clone https://github.com/tiagojct/subsub.git
cd subsub
npm install
npm test
npm run build
End-to-end tests (real pi and Python servers, a fake Zotero, a scripted model): ZLM_DIR=/path/to/zotero-local-mcp npm run test:e2e.
Changes
See CHANGELOG.md.
Cite
Jacinto T. Sub-Sub: a research assistant for Zotero [software]. Porto: Faculdade de Medicina da Universidade do Porto; 2026. doi:10.5281/zenodo.23238602
This DOI always points to the latest version; each version also has its own DOI on Zenodo. CITATION.cff has the same reference for citation managers.
Licence
MIT, Tiago Jacinto. The /lit, /compare and /review prompts adapt text from Feynman (MIT); see THIRD_PARTY_NOTICES. Literata and Atkinson Hyperlegible fonts: SIL Open Font License.
