carrel

A carrel is a private study desk in a library: your materials close at hand, organized your way. carrel is that desk for your local files — pdf, docx, odt, epub, rtf, xlsx, md, html, txt, json, xml, csv, and png/jpg/ico images — with 26 commands to convert, OCR, inspect, diff, index, search, pack, watch, and more. And it treats AI agents as first-class users of the desk: every data-producing command speaks --json with stable exit codes, carrel pack turns file trees into LLM-ready context, and the repo doubles as a Claude Code plugin marketplace whose plugins drive the same CLI.

What can it do

carrel wraps the masters — pandoc, poppler, qpdf, tesseract/ocrmypdf, ImageMagick, exiftool, ffmpeg… — behind one adapter layer with capability detection. Missing binary? Commands degrade with an install hint (exit 3), never a crash. Several copies of a tool on PATH? Pin one with CARREL_BIN_<NAME> (docs/CONFIGURATION.md).

Quickstart

Requires Python ≥ 3.12 and uv. No checkout needed:

uv tool install 'carrel[all]'   # or: pipx install 'carrel[all]' — puts `carrel` on your PATH
                                # plain `carrel` skips the TUI and office/token extras (see INSTALL)
carrel doctor         # what can your desk do today? (+ apt hints for the rest)

(Contributing or hacking on it? uv tool install . from a checkout does the same thing.)

A first taste:

carrel inspect paper.pdf                              # pages, sha256, producer, form fields…
carrel convert minutes.docx --to md                   # office/ebook formats read and write via pandoc
carrel index . && carrel search "marginal notes"      # FTS5 over your whole desk
carrel pack src/ --format xml -o context.xml --stats  # LLM-ready context + token table
carrel pack docs/ --query "release checklist" --stats # only the files the index ranks relevant
carrel catalog export -o desk.json                    # tags + notes, portable and diff-able

Add --json to any of these and you get machine-readable output on stable exit codes — that's the whole agent contract. Tab completion: eval "$(carrel completion bash)" (zsh and fish too).

The marketplace

This repo is also a Claude Code plugin marketplace: plugins whose slash commands, agents, skills, and hooks all delegate to the CLI above. The table below is a snapshot — docs/MARKETPLACE.md is authoritative for the current plugin list.

claude plugin marketplace add coltonbearden/carrel
claude plugin install carrel-inspect@carrel

Install the CLI first (see Quickstart) so the plugins can call it. Works headless too:

claude -p "/carrel-inspect:inspect text+image.pdf" --allowedTools "Bash(carrel:*)"

The full validated flow (with real output) is in docs/TEST_REPORT.md.

The desk TUI

carrel desk

The flagship: a three-pane Textual desk. A file tree on the left, an inspector in the middle (metadata, preview, tags, notes), an action palette on the right (convert, ocr, pack, thumbnail…) — all driving the same core library as the CLI, with full-text search along the bottom. Theme: warm lamplight on dark wood, per docs/BRAND.md.

Learn more

• The docs site — everything below, browsable
• docs/HOW_THIS_WAS_BUILT.md — the autonomous single-day build, from the primary sources
• docs/VISION.md — why a library desk, and the product principles
• docs/ARCHITECTURE.md — the adapter layer, the index, the plugin design
• docs/FEATURES.md — the capability × strategy matrix
• docs/TEST_REPORT.md — everything above, executed for real (855 tests; cookbook runs; office and pack --query proofs)
• examples/cookbook/ — ten end-to-end recipes, from scan→searchable-notes to pack-what-matters
• docs/BRAND.md — palette, typography, logo usage, voice

License

MIT © Colton Bearden

Related projects

• brainrot — Self-audit toolkit for Claude: mine your own chat history for corrections and wins, arbitrate findings into a lean rule set, keep memory tidy