ref-manager
ref-manager icon

Claude Code plugin · v0.2.0 · phases 0–11

A paper library you can cite, check, and reason over

ref-manager turns PubMed IDs into a personal, PMID-keyed library: resolved metadata, immutable full-text snapshots, provenance-backed claims, and a concept graph. You drive it from Claude Code with /ref:* slash commands. Nothing enters the library unless you put it there, and every answer it writes cites evidence you can open.

How a paper moves through it

you choose PMID list, or picked search hits /ref:add <pmid…> 1 RESOLVE metadata · authors 2 DEDUP PMID identity · citekey 3 TIER abstract, or unavailable 4 WRITE meta · authorship · funding OPTIONAL, PER PAPER /ref:fetch · /ref:attach PMC JATS → Unpaywall → HTML, or your own PDF → source.md /ref:extract one ref-extractor agent per PMID → claims.json 5 WEAVE /ref:weave → concepts, relations, OKF views index/catalog.sqlite FTS5 · rebuildable projection find search · ask · related compare & write compare · summarize verify check-citations · verify discover gaps · hypothesize hand off export · cite · report
always runs on ingest on demand, per paper your decision
Acquisition failures never block ingestion: a paper with no reachable full text stays a first-class abstract-tier record, visibly labelled. Files on disk are the authority; the SQLite index and OKF views are projections that /ref:index --rebuild reconstructs (and /ref:ask rebuilds before retrieving). Stage-by-stage detail is on Workflows.

Sixty seconds

Inside Claude Code, with the plugin installed:

› /ref:init ~/Research/library
  # creates the library, records it in ~/.config/ref-manager/config.json
› /ref:add 31452104 30679568
  # resolves both PMIDs through PubMed, allocates citekeys, marks each abstract-tier
› /ref:project create thesis-ch3 --scope "Cortical thickness in autism"
› /ref:ask "Is cortical thickness altered in autistic adults?" --project thesis-ch3
  # one grounded answer, every sentence cited as [^pmid]

The PMIDs above are placeholders; the full walkthrough in Get started shows each command's real output.

Where to go

Start hereGet startedInstall, create a library, ingest your first papers, and search them. VisualWorkflowsDiagrams of the ingest pipeline, full-text acquisition, review overlays, and synthesis. Hands-onTutorialsAdding papers, a thesis chapter, a systematic review, a PI report, the Papers handoff, and graph discovery. ReferenceSlash commandsAll 40 /ref:* commands: arguments, what they write, examples. ModelConceptsLibrary layout, ownership rules, extraction tiers, selectors, and identifiers. InternalsAPIPython scripts and their CLIs, record schemas, and the two subagent contracts.

Design commitments

RuleWhat it means for you
PMID is identityEvery paper resolves to a PubMed ID before anything else. DOI or title matches flag inconsistencies but never merge records.
Library starts emptyNo bulk import, no scheduled jobs. Saved searches re-run only when you ask.
Raw is immutableFetched PDFs, JATS, and metadata responses are stored byte-identical under their hash. Derived text and claims are versioned beside them.
Your content is yoursnotes.md, annotations, and review decisions are never overwritten by regeneration.
Tiers stay visibleEvery citation says whether an abstract or full text backed it, and what the paper's retraction status was.
Sets are frozenCommands take one selector grammar and record the PMIDs they resolved to, so a saved comparison never changes membership silently.