The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Code of Paper listing page.
Discover GitHub implementations of research papers — from the terminal.
Search 181k+ arXiv papers and find their code on GitHub. Works for humans and AI agents alike.
Or with pipx for isolated installs:
Requires Python 3.10+. No API key needed — works anonymously at 60 requests/minute.
Use -o / --output before the subcommand:
| Format | Flag | Use case |
|---|---|---|
| Table | -o table | Human reading (default) |
| JSON | -o json | Scripts, jq pipelines, full response data |
| Quiet | -o quiet | IDs only, one per line — pipe into other commands |
| JSONL | -o jsonl | Streaming, append to files, batch processing |
| BibTeX | -o bibtex | Citation managers, LaTeX bibliographies |
| CSV | -o csv | Spreadsheets, pandas, data analysis |
The shorthand -q is equivalent to -o quiet:
You can set a default format via config so you don't need -o every time:
| Command | Description | Example |
|---|---|---|
search | Full-text paper search | codeofpaper search "vision transformers" --has-code |
paper | Paper details by arXiv ID or URL | codeofpaper paper 2010.11929 |
code | GitHub repos implementing a paper | codeofpaper code 1706.03762 |
similar | Semantically similar papers | codeofpaper similar 2010.11929 |
suggest | Autocomplete / quick lookup | codeofpaper suggest "attention" |
random | Random interesting paper | codeofpaper random --quality high |
| Command | Description | Example |
|---|---|---|
trending | Trending papers by category | codeofpaper trending --category cs.CV --sort hot |
categories | List categories or get details | codeofpaper categories cs.AI |
conferences | List all conference series | codeofpaper conferences |
conference | Papers from a specific conference | codeofpaper conference neurips_2024 --has-code |
code-drops | Recent conference papers with new code | codeofpaper code-drops --days 7 |
repo | Reverse lookup: repo → paper | codeofpaper repo google-research/vision_transformer |
open | Open paper or repo in browser | codeofpaper open 2010.11929 --code |
| Command | Description | Example |
|---|---|---|
research | Structured research overview | codeofpaper research "RL" --depth deep |
batch | Process multiple IDs from stdin/file | cat ids.txt | codeofpaper batch paper |
export | Paginated bulk export | codeofpaper export trending -o csv > out.csv |
| Command | Description | Example |
|---|---|---|
auth | Manage API key (setup/status/clear) | codeofpaper auth status |
status | Check API health and stats | codeofpaper status |
Options: --limit, --offset, --sort (relevant, recent, has_code), --has-code, --category.
Multi-step orchestrated overview of a research topic:
| Depth | Steps | API calls |
|---|---|---|
shallow | Search only + landscape statistics | 1 |
medium | Search + repos for top papers (default) | ~6 |
deep | Search + repos + similar papers from #1 | ~8 |
Process multiple queries or IDs from a file or stdin. Always outputs JSONL regardless of -o:
Supported commands: paper, search, code, similar, suggest.
Each line produces one JSON object:
Options: --delay (seconds between calls, default 0.5).
Paginated bulk export from trending, conference, or search:
Auto-paginates through results (100 per page, 0.5s delay). Options: --max (default 200), --has-code, --category, --days.
The CLI is designed for AI agent consumption. Key features:
Agents can branch on exit codes without parsing error messages:
| Exit Code | Meaning | Agent Action |
|---|---|---|
| 0 | Success | Parse stdout |
| 1 | General error | Log and report |
| 2 | Connection error | Retry with backoff |
| 3 | Not found (404) | Skip or try different ID |
| 4 | Rate limited (429) | Wait and retry |
| 5 | Auth required (401/403) | Run codeofpaper auth setup |
Responses are cached on disk for 30 minutes (~/.cache/codeofpaper/http/), so repeated calls are instant and free.
Code of Paper ships an optional Model Context Protocol server that exposes paper / code lookup as tools to any MCP-compatible agent — Claude Desktop, Cursor, Continue, Cline, Zed, etc.
Install with the mcp extra:
This adds a codeofpaper-mcp entry point that speaks MCP over stdio.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows), or ~/.config/Claude/claude_desktop_config.json (Linux):
This pulls + runs the server on demand — no global install needed. If you've already pip install'd the package, you can replace the command with just "codeofpaper-mcp" and drop args.
Most MCP clients accept the same shape:
| Tool | Purpose |
|---|---|
paper_lookup(paper_id_or_url) | Paper metadata + confident-tier repos |
code_for_paper(paper_id_or_url, limit, include_possible) | Ranked GitHub repos implementing a paper |
search_papers(query, limit, year, venue, has_code) | Free-text paper search with filters |
All tools are read-only, return plain JSON, and surface API errors as {"error": "...", "status": N} rather than throwing — agents get structured output either way.
Config is stored as JSON via platformdirs:
| OS | Path |
|---|---|
| Linux | ~/.config/codeofpaper/config.json |
| macOS | ~/Library/Application Support/codeofpaper/config.json |
| Windows | %APPDATA%\codeofpaper\config.json |
Fields:
No config file needed — everything works out of the box with sensible defaults.
Options are resolved in this order (first wins):
--api-url, --api-key, --ca-bundle, -o)CODEOFPAPER_API_URL, CODEOFPAPER_API_KEY, CODEOFPAPER_CA_BUNDLE, CODEOFPAPER_OUTPUT, CODEOFPAPER_TIMEOUT)If you're behind a corporate proxy that performs TLS inspection (man-in-the-middle), you'll see an SSL error like:
To fix this, point the CLI at your corporate CA certificate bundle (PEM file). Three equivalent ways, in priority order:
Ask your IT department for the CA certificate file if you don't have it.
Tip: If you've already set
SSL_CERT_FILEfor other tools (pip, curl, etc.), httpx respects that variable automatically — no extra configuration needed.
copBoth codeofpaper and cop are installed as entry points:
Note: If
copconflicts with another tool on your system, usecodeofpaperinstead.
Install tab completion for your shell:
Supports bash, zsh, fish, and PowerShell. After installing, restart your shell or source the completion file.
MIT