bibox

Using AI agents (OpenClaw) to search and summarize papers? Let them manage your bibliography and notes too. You just browse the TUI. bibox makes it work.

Just give your agent the GitHub link. It'll figure out the rest.

For humans: browse and edit in the TUI. For agents: manage entries and notes through the CLI.

Best for: researchers who use AI agents for literature review and want papers, notes, and BibTeX in one Git-syncable folder.

Not for: GUI, PDF annotation, or Word integration. Use Zotero instead.

Sources: Crossref, Open Library, arXiv, Unpaywall Formats: BibTeX, YAML, RIS, CSV, Markdown Import: .bib, .ris from Zotero, Mendeley, EndNote

Features

• Smart import - Drop a PDF and bibox extracts the DOI, fetches metadata from Crossref, and files it automatically
• Multiple sources - Add entries via PDF, DOI, ISBN, arXiv ID, URL, or title search
• Three-panel TUI - Collections, entries, and preview (info / notes / PDF) side by side
• Vim-style navigation - hjkl, gg/G, {n}j, Ctrl+d/u, multi-select with Space
• Fetch & refresh - Press f to pull metadata from Crossref, preview changes, pick which fields to update
• Undo/redo - Ctrl+z/Ctrl+y with in-memory snapshots
• AI-agent-friendly - Every command supports --json. Notes have --stdin, --section, --template for programmatic access
• Markdown notes - Per-entry notes with section-level updates, rendered with syntax highlighting in the TUI
• Sub-collections - Hierarchical collections with path notation (digest/2026-04). Unlimited depth, works like a filesystem
• Portable home - bibox init puts everything in one Git-syncable folder
• Export - BibTeX, YAML, RIS, CSV, notes (.md). Include PDFs. Copy to clipboard. Zip it up.
• Templates - Built-in and custom note templates with {{variable}} substitution
• Doctor - bibox doctor diagnoses and auto-repairs DB issues: bad citekeys, LaTeX escapes, orphaned files

Install

With Rust (macOS / Linux desktop):

cargo install bibox

With cargo-binstall (fast, no compile):

cargo binstall bibox

On a server (no Rust needed):

curl -L https://github.com/namil-k/bibox/releases/latest/download/bibox-x86_64-unknown-linux-musl -o ~/.local/bin/bibox
chmod +x ~/.local/bin/bibox

Pre-built binaries for Linux x86_64, macOS arm64, and macOS x86_64 are available on the releases page.

Update:

bibox update

Quick Start

Add a paper by PDF (auto-extracts DOI → fetches metadata):

bibox add paper.pdf

Add by DOI, arXiv ID, ISBN, or URL:

bibox add --doi 10.1145/3290605.3300907

bibox add --arxiv 2301.12345

bibox add --isbn 978-0-13-468599-1

bibox add --url https://arxiv.org/abs/2301.12345

Search by title on Crossref:

bibox add --search "attention is all you need"

Add a web page, product, or any non-paper reference as misc:

bibox add --title "Varjo Aero" --url https://varjo.com/products/aero/ --author "Varjo" --year 2024

Launch TUI:

bibox

TUI

┌ Collections ─┬ Entries ──────────┬ Info │ Note │ PDF ──┐
│ > All (15)   │  1  kim2025 ◆     │ Title: Rust Syst.. │
│   cs (8)     │  2  dijkstra1968  │ Author: Kim, J.    │
│   ml (5)     │  3  manco2017 ◆   │ Year: 2025         │
│              │                   │ DOI: 10.1234/...   │
├──────────────┴───────────────────┴────────────────────┤
│ / search  s sort  o open  w web  e export  ? help     │
└───────────────────────────────────────────────────────┘

Keybindings

Key	Action
h/l	Focus left/right panel
j/k	Navigate within panel
gg/G	Jump to top/bottom
{n}j	Move n lines (e.g., 5j)
Ctrl+d/u	Half-page down/up
Tab	Switch preview mode (Info → Note → PDF)
Space	Toggle select entry
V	Select/deselect all
/	Search (entries or collections, based on focus)
s	Sort menu
f	Fetch/refresh metadata from Crossref (preview changes, select which to apply)
o	Open PDF (or fetch from web; re-fetches if file missing; opens browser on 403)
A	Attach a local PDF via file picker (copies and renames to citekey.pdf)
w	Open paper web page in browser
e	Export menu (selected / collection / all)
y	Copy citekey to clipboard
d	Delete entry
c	Manage collections (works on multi-selected entries too)
t	Edit tags
N	Edit note in $EDITOR
Ctrl+z	Undo
Ctrl+y	Redo
,	Settings (line numbers, panel ratio, citekey format, export dirs, git sync)
?	Help
q/Esc	Quit

CLI

Browse:

bibox list                          # Show collections with counts

bibox list ml                       # List entries in a collection

bibox show kim2025rust              # Full entry details

bibox search "transformer"          # Interactive search

Edit:

bibox edit kim2025rust --title "New Title"

bibox edit kim2025rust --doi 10.1234/new   # Re-fetch metadata from Crossref

bibox edit kim2025rust --tags-add "ml,nlp"

Collections:

bibox collect kim2025rust ml systems       # Add to collections

bibox collect kim2025rust digest/2026-04   # Add to sub-collection

bibox list digest                          # List digest + all sub-collections

bibox uncollect kim2025rust ml             # Remove from collection

Import (from Zotero, Mendeley, EndNote, etc.):

Export your library as .bib or .ris from any reference manager, then:

bibox import library.bib                     # Import from BibTeX
bibox import library.ris                     # Import from RIS
bibox import ml-papers.bib --to ml           # Import into a collection

Migrating from Zotero? Export each collection as a separate .bib or .ris and import with --to:

bibox import zotero-ml.bib --to ml
bibox import zotero-cv.ris --to cv
bibox import zotero-acl2025.bib --to digest/acl2025

Or just give the file to your agent. It'll handle it.

Export:

bibox export                               # Print all as BibTeX to stdout
bibox export > refs.bib                    # Redirect to file
bibox export -o refs.bib                   # Same, explicit output path
bibox export kim2025 dijkstra1968          # Export specific entries
bibox export --collection cs --format ris  # Export collection as RIS
bibox export --include-pdf --zip           # BibTeX + PDFs, zipped

bibox export --notes-only -o ~/notes       # Export all note .md files to folder

bibox export --collection ml --notes-only -o ~/ml-notes  # Collection notes only

Bulk update:

bibox modify year=2025 --filter "collection:ml" --yes

Delete:

bibox delete kim2025rust

Attach a PDF manually (when auto-fetch fails):

bibox edit kim2025rust --attach-pdf ~/Downloads/paper.pdf

Diagnose and repair database issues:

bibox doctor            # Detect malformed entries, missing PDFs, orphaned notes
bibox doctor --fix      # Auto-repair fixable issues
bibox doctor --json     # Machine-readable output

Config:

bibox config --json                        # View all settings and paths

Notes

Notes are Markdown files, one per entry. Designed for both human editing and AI agent pipelines.

Initialize from a template:

bibox note kim2025rust --template ai-summary

AI agent writes sections programmatically:

echo "Proposes a novel approach..." | bibox note kim2025rust --stdin --section "Summary"

echo "CIFAR-10: 95.2% accuracy" | bibox note kim2025rust --stdin --section "Results"

Read note back:

bibox note kim2025rust --show

Human edits in $EDITOR:

bibox note kim2025rust

Templates

bibox template list                             # List all templates

bibox template show ai-summary                  # Print template content

bibox template create my-review --stdin < t.md  # Create custom template

bibox template edit ai-summary                  # Edit in $EDITOR

bibox template delete my-review                 # Delete custom template

Built-in templates: ai-summary, reading-notes. Custom templates override built-ins.

Template variables: {{title}}, {{citekey}}, {{doi}}, {{year}}, {{author}}, {{journal}}, {{booktitle}}, {{publisher}}

Portable Home & Git Sync

# Initialize a portable bibox home
bibox init ~/bibox

# Everything lives in one folder
~/bibox/
├── db.json       # Database
├── pdfs/         # PDF files
└── notes/        # Markdown notes

# Sync with Git
cd ~/bibox && git init && git add . && git commit -m "init"
git remote add origin git@github.com:you/bibox-library.git
git push -u origin master

# Or use the TUI: press , → Git → Enter to check status → Enter to sync

Settings

Press , in the TUI, or run bibox config to see all current settings and paths.

line_numbers = "absolute"              # absolute, relative, none
panel_ratio = [2, 4, 4]               # left : center : right (sum = 10)
citekey_format = "{author}{year}{title}" # {author}, {year}, {title} variables
bib_export_dir = "."                   # BibTeX export location
export_dir = "~/Downloads"             # Other exports location
home = "~/bibox"                       # Portable home (set by bibox init)

AI Agent Integration

If you are an AI agent: run bibox agent-guide first. It prints a complete reference of all commands, flags, and workflows designed for programmatic use.

bibox agent-guide          # Full agent reference (text)
bibox agent-guide --json   # Same, as structured JSON

Every command supports --json for machine-readable output.

# Full workflow: search → add → note → push
bibox add --search "attention is all you need" --index 0 --to ml --json
bibox note vaswani2017attention --template ai-summary
echo "The paper proposes..." | bibox note vaswani2017attention --stdin --section "Summary"
echo "1. Multi-head attention..." | bibox note vaswani2017attention --stdin --section "Key Contributions"

# Get all paths programmatically
bibox config --json

# Non-interactive sync
bibox sync --yes --json

Flag	Purpose
--json	Machine-readable output (most commands)
--index N	Auto-select Nth search result (0-based, with --search)
--stdin	Read content from stdin (notes, templates)
--section "Name"	Target a specific ## Heading in a note
--yes / -y	Skip confirmation prompts
--template <name>	Initialize note from template

License

MIT