paperhound

Sniff. Fetch. Read.
A researcher's best friend, right in your terminal.

Website · Install · Commands · Meet the hound

paperhound is a fast, agent-ready CLI for AI/ML researchers and tooling authors. One binary to search, inspect, download, and convert to Markdown academic papers from many sources at once — arXiv, OpenAlex, DBLP, Crossref, Hugging Face Papers, Semantic Scholar and CORE. Conversion is powered by docling, so the resulting Markdown is good enough to feed straight into an LLM context window.

Meet the hound

Long ears, a red neckerchief, and a nose for good research. Paperhound is our paper-fetching companion: it follows the literature and brings something worth reading back to your desk.

paperhound mascot             # a little ASCII company, entirely offline
paperhound mascot --animate   # a two-second sniff-and-fetch animation

Animation is opt-in and plays only in a capable interactive terminal. Pipes, CI, small/dumb terminals, NO_COLOR, and PAPERHOUND_NO_ANIMATION=1 use a single static portrait. Research commands and JSON output stay unchanged. The website has installation commands, a command overview, and a workflow preview with pause and reduced-motion support. Mascot artwork and design notes.

Features

• 🔎 Unified search — one query, many backends in parallel under a 10-second budget. Results merged round-robin (no provider can monopolize the top-N) and deduplicated by arXiv id / DOI / title.
• 📄 Inspect before downloading — abstract + metadata in one call.
• ⬇️ Download by identifier — arXiv id, DOI, Semantic Scholar id, or any paper URL. Open-access PDFs are resolved automatically.
• 📝 PDF → Markdown via docling — figures, LaTeX equations and HTML tables are opt-in flags.
• 📚 Local library — SQLite FTS5 at ~/.paperhound/library/. Add a paper, store its Markdown, then offline-grep over titles, abstracts and bodies.
• 🧠 Embedding rerank — install paperhound[rerank] and the CLI reranks search results by query/abstract similarity automatically.
• 🤖 Agent-ready — search, metadata, and citations support --json, and a skills.sh skill ships in this repo for one-line install.
• 🔗 Citation graph — refs and cited-by walk the OpenAlex / Semantic Scholar graph with depth control.
• 📤 Export — BibTeX, RIS, CSL-JSON straight from show.

Install the agent skill (recommended first step)

The fastest way to use paperhound is from an agent (Claude, OpenAI, opencode, …). Install the skill — it teaches the agent every command, flag, and JSON schema:

npx skills add alexfdez1010/paperhound

This places SKILL.md in your agent's skill directory (~/.claude/skills/paperhound/ for Claude Code). Pass -a <agent> to target a specific agent (e.g. -a claude-code, -a opencode).

The skill auto-installs the paperhound CLI on first use, so you don't need to install anything else manually.

Install the CLI

# pip
pip install paperhound

# uv (isolated CLI on $PATH)
uv tool install paperhound

# uv — upgrade later
uv tool upgrade paperhound

# uv (as a library inside another project)
uv add paperhound

Optional embedding rerank:

pip install 'paperhound[rerank]'

Python 3.10+ is required.

CLI usage

Once installed, paperhound is on your $PATH.

# 🔎 Search across all providers
paperhound search "diffusion transformers" --limit 5

# 📄 Show abstract + metadata
paperhound show 2401.12345
paperhound show 10.1038/s41586-020-2649-2          # DOI
paperhound show https://arxiv.org/abs/1706.03762   # URL
paperhound show 2001.08361 -s arxiv                # force a single provider

# ⬇️ Download the PDF
paperhound download 1706.03762 -o ./papers/

# 📝 Convert a local PDF to Markdown
paperhound convert ./papers/1706.03762.pdf -o attention.md

# 🪄 Or do it all at once: resolve, download, convert, clean up
paperhound get 1706.03762 -o attention.md

Commands

Run paperhound <command> --help for full options.

JSON output

--json is the pipe-friendly mode: no headers, no Rich formatting, no progress bars.

# JSONL — one compact JSON object per line
paperhound search "graph neural networks" --json | jq '.title'

# Single compact JSON object
paperhound show 1706.03762 --json | jq .abstract

Schema: paperhound.models.Paper via model_dump(mode="json"). Fields include title, authors[], abstract, year, venue, publication_type (journal/conference/preprint/book/other), url, pdf_url, citation_count, identifiers.{arxiv_id,doi,…}, sources[].

Filters

paperhound search supports the filters below, pushed down to providers that support them (OpenAlex, Crossref, Semantic Scholar) and re-applied client-side as a safety net.

paperhound search "vision transformers" --year 2022-2024 --min-citations 100
paperhound search "deep learning" --venue NeurIPS --author Hinton
paperhound search "diffusion models" --peer-reviewed
paperhound search "agentic workflows" --preprints-only

Papers with unknown year/venue are kept (filter unverifiable); papers with unknown citation_count or unknown publication_type are excluded when the matching filter (--min-citations, --type, --peer-reviewed, or --preprints-only) is set.

Conversion options

paperhound convert paper.pdf -o paper.md --with-figures --equations latex --tables html

Export formats

paperhound show 1706.03762 --format bibtex
paperhound show 1706.03762 --format ris
paperhound show 1706.03762 --format csljson

BibTeX cite keys are derived as <firstAuthorLastName><year><firstSignificantTitleWord> (accents stripped, lowercased). LaTeX special characters are escaped automatically.

Local library

paperhound add 1706.03762
paperhound add 1706.03762 --convert
paperhound list
paperhound grep "attention mechanism"
paperhound rm 1706.03762

Default location: ~/.paperhound/library/ (override with PAPERHOUND_LIBRARY_DIR). Re-adds are idempotent.

Citation graph

paperhound refs 1706.03762
paperhound cited-by 1706.03762 --depth 2 --limit 50
paperhound refs 1706.03762 --source semantic_scholar --json | jq '.[].title'

Default provider order: OpenAlex first, Semantic Scholar fallback. Results are deduplicated by arXiv id / DOI / title. At --depth 2, total fetched is capped at limit * 2.

Rerank

With paperhound[rerank] installed, every CLI search reranks results by embedding similarity between the query and each candidate's title + abstract.

paperhound search "vision language models"          # rerank on by default
paperhound search "graph neural networks" --no-rerank
paperhound search "agents" --rerank-model sentence-transformers/all-mpnet-base-v2

Without the extra installed, the CLI silently falls back to merge-order ranking — no error, no hang.

Identifier formats

paperhound accepts whatever you have on hand:

• arXiv ids: 2401.12345, 2401.12345v3, cs.AI/0301001, arXiv:2401.12345
• DOIs: 10.1038/s41586-020-2649-2, doi:10.1038/...
• Semantic Scholar paper ids: 40-char hex
• URLs: arxiv.org/abs/..., arxiv.org/pdf/..., doi.org/..., semanticscholar.org/paper/...

Configuration

Run paperhound providers (or paperhound providers --json) to see, at a glance, which providers are configured on the current machine and what to export to enable or upgrade each one.

More

• 🐍 Using paperhound from Python — library API, building a corpus, citation graph, adding a new provider.
• 🛠️ Development — tests, lint, releasing to PyPI.
• 🧪 Testing procedure — standardized post-publish smoke pass.

License

MIT — see LICENSE.