Paperstack

Paperstack is an open-source CLI for maintaining, querying, and publishing an independently authored research corpus. The software and corpus are separate: Paperstack can be public while each corpus and its editorial judgments remain under its maintainer's control.

It can search typed reviews, initialize and validate entries, inspect external paper metadata, read arXiv sources, manage a selected-venue DBLP index, and build a static viewer. A synthetic corpus lives in examples/corpus; no assessment of real work is bundled with the package.

Install

uv tool install paperstack-cli

PDF conversion is optional:

uv tool install 'paperstack-cli[pdf]'

The PDF extra uses pdf-inspector for native extraction and selective OCR. Clean text PDFs need no external runtime, while routed OCR pages require the pinned PDFium and ONNX Runtime libraries described in the OCR runtime guide. The first routed page downloads and verifies the pinned OCR model set unless an offline model directory is configured. When the shared libraries are not on the platform search path, point pdf-inspector at the extracted files:

export PDFIUM_LIB_PATH=/absolute/path/to/libpdfium.so
export ORT_DYLIB_PATH=/absolute/path/to/libonnxruntime.so

The runtime guide lists the matching downloads and filenames for Linux, macOS, and Windows.

AI agent skill

Paperstack ships an Agent Skills-compatible skill for Codex, Claude Code, and other compatible agents. Install the CLI first, then add the skill globally with the open skills CLI:

npx skills add MilkClouds/paperstack --skill paperstack -g

The installer detects supported agents such as Codex and Claude Code; pass -a codex -a claude-code to target them explicitly, or omit -g for a project-local installation. The shared SKILL.md keeps corpus selection, source inspection, entry authoring, validation, and viewer workflows consistent without exposing a private corpus. Use npx skills update paperstack -g to update it later.

Choose a corpus

Register either a local working tree or a GitHub repository. The first registered corpus becomes active.

paperstack corpus add work --path ~/research/reviews
paperstack corpus init new --path ~/research/new-corpus
paperstack corpus add private --repo OWNER/private-reviews
paperstack corpus list
paperstack corpus use private
paperstack corpus remove work
paperstack corpus remove private --purge-cache --yes

Private GitHub repositories use the existing gh login without storing its token:

gh auth login
paperstack review sync

PAPERSTACK_DIR and PAPERSTACK_REPO remain available for automation. Explicit environment variables take priority, then a surrounding corpus working tree, then the active profile. Profiles are stored in ${XDG_CONFIG_HOME:-~/.config}/paperstack/config.json.

Provider credentials can be stored once without adding them to a project .env:

paperstack config set semantic-scholar.api-key
paperstack config status
paperstack config paths
paperstack config unset semantic-scholar.api-key

set prompts without echoing the value; use --stdin to pipe it from a password manager. Credentials are written atomically to ${XDG_CONFIG_HOME:-~/.config}/paperstack/credentials.json, with mode 0600 on POSIX systems. Exported environment variables take priority, followed by the nearest .env, then the credential store. GitHub Actions can therefore keep using repository secrets through environment variables.

Review corpus

paperstack review show example2026paperstack --brief
paperstack review show arxiv:2410.24164 --json
paperstack review list --quality good --tag vla
paperstack review search "flow matching"
paperstack review init <key> --id arxiv:NNNN.NNNNN --title "Verbatim title" --editor <name>
paperstack review check --style
paperstack review audit
paperstack review citations --fetch

Paper entries, talks, and posts use separate contracts under entries/{papers,talks,posts}/. The complete schemas, writing guide, and source-reading workflow are in Entry authoring.

Inspect papers

These commands use external source records and do not select a citation or make an editorial judgment:

paperstack paper search "Attention Is All You Need" --source dblp
paperstack paper search "Exact Paper Title" --source openreview --exact-title --openreview-status accepted
paperstack paper search "robot learning" --source semantic-scholar --year 2024-2026
paperstack paper search 'ti:"robot learning"' --source arxiv --category cs.RO --sort date
paperstack paper metadata arxiv:2106.09685
paperstack paper metadata doi:10.1109/CVPR.2016.90 --source crossref
paperstack paper citations arxiv:2106.09685 --limit 50
paperstack paper references doi:10.48550/arXiv.2106.09685 --limit 50
paperstack paper read arxiv:2604.23073 --outline
paperstack paper read arxiv:2604.23073 --section 6
paperstack paper pdf arxiv:2602.09017

metadata accepts arxiv:, doi:, dblp:, and openreview: references. read and pdf require an arxiv: reference. authors, citations, and references use Semantic Scholar and also accept its s2:, corpus:, acl:, pmid:, and mag: identifiers. Structured commands expose scoped --json flags; networked commands expose scoped --offline flags. Paperstack reports source records but does not synthesize a citation entry or choose which version of a work should be cited.

OpenReview exact-title search uses its title-only exact mode and verifies a normalized title match locally. Status filtering is conservative because venues encode decisions and withdrawals differently; Paperstack infers it from public invitation, venue, decision, and status fields rather than treating it as a universal field.

Build a viewer

paperstack viewer build
paperstack viewer serve --port 8000

The viewer is generated from the selected corpus. Source Markdown remains available alongside the rendered pages.

DBLP index

The optional selected-venue index accelerates DBLP search and is required by review audit:

paperstack index dblp status
paperstack index dblp install
paperstack index dblp update

Installed snapshots are content-addressed and verified by SHA-256, schema, and embedded metadata before an atomic pointer switch. See DBLP snapshot releases for maintenance.

Configuration

Variable	Purpose
PAPERSTACK_DIR	Explicit local corpus working tree
PAPERSTACK_REPO	Explicit GitHub corpus in OWNER/REPO form
PAPERSTACK_TTL	Remote corpus cache refresh interval; default 3600 seconds
PAPERSTACK_PAPERS_DIR	arXiv source and PDF cache
SEMANTIC_SCHOLAR_API_KEY	Optional higher-rate Semantic Scholar access
OPENREVIEW_ACCESS_TOKEN	Optional OpenReview access cookie value
XDG_CONFIG_HOME	Corpus profile and credential configuration root
XDG_CACHE_HOME	Remote corpus and paper cache root
XDG_DATA_HOME	DBLP index root

The console entry point also loads the nearest .env without overriding exported variables. Review exit codes are 0 for hits, 1 for no match, 2 for ambiguity, and 3 for unavailable data or invalid configuration.

Development

uv run --group lint ruff check .
uv run --group lint ruff format --check .
uv run --group test pytest -q
PAPERSTACK_DIR=examples/corpus uv run paperstack viewer build --output /tmp/paperstack-site

Paperstack is licensed under Apache-2.0. Corpora are separate works and may use their own terms.