Read, index, pack and file your documents — from the terminal, for you and your agents.

carrel pack src --stats — the token table, before you spend a context window on it.

carrel redact — true raster redaction of a PDF, and the proof: grep exits 1.

carrel turns the documents on your disk — PDFs, Word and OpenDocument files, ebooks, spreadsheets, email, scans — into text you can search, fields you can query, and context you can hand to an LLM. One CLI; every data command speaks --json with stable exit codes; the commands that move your files (organize, rename, intake, dedupe) dry-run by default; a conversion refuses to overwrite its output without --force. It ships an MCP server and a Claude Code plugin marketplace that drive the same commands, so Claude can read your .docx, pack the five relevant files out of five hundred, and file an invoice inbox by what the invoices say. Missing pandoc or tesseract? carrel doctor tells you what works today and how to unlock the rest.

A carrel is a private study desk in a library: your materials close at hand, organized your way.

Install

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? (+ install hints for the rest)

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

Three things to try

Give Claude the right context

Index a folder once, then let the desk's own ranking choose what to send. --since does the same job from git history instead of a query.

carrel --root ~/papers index                                   # the desk lives in ~/papers/.carrel
carrel --root ~/papers pack ~/papers --query "attention" --stats
carrel pack . --since HEAD~5 --stats                           # or: what git touched

--root names the desk. Without it the index lands in the directory you happened to run from, and the next --query cannot find it.

The MCP server (carrel mcp, shipped by the carrel-agent plugin) exposes the same thing as a tool, confined to the directory it starts in.

Limitation: query terms must appear in the text — FTS5 AND-s them, so a natural-language question often matches nothing. Under --json an empty pack exits non-zero rather than handing you a valid, empty document.

Read what the agent can't

Claude's Read cannot open a .docx, an .xlsx or an .eml at all. Install the guard plugin once and those files arrive as text, without you converting anything by hand.

claude plugin marketplace add coltonbearden/carrel   # the plugin marketplace, not the CLI
claude plugin install carrel-guard@carrel

Office, ebook, email and spreadsheet files become text automatically before Claude's Read sees them; PDFs become cheap text; images stay pictures for Claude's own vision.

Limitation: layout-heavy PDFs and diagrams still want the visual Read — the guard's note tells Claude where the original is and when to prefer it (CARREL_GUARD_PDF_TEXT=0).

Turn an inbox into an archive

Read what each document says, then file it by that. The dry run is the default; nothing moves until --apply.

carrel fields ~/inbox/invoice.pdf              # vendor, dates, totals, with confidence
carrel intake ~/inbox --to ~/archive           # dry run: shows every planned move
carrel intake ~/inbox --to ~/archive --apply   # files into YYYY/MM, indexes, records fields
carrel --root ~/archive meta find 'total>1000' 'due<2026-11'

Limitation: field extraction is English-label heuristics with a confidence column — read it before --apply. Originals are always kept.

Status and support

A solo-maintainer project, used daily by its author.

Settled interfaces — convert, inspect, index/search, pack: the flags and the --json shapes are what they will stay. Still moving — carrel mcp and the carrel-guard hook do useful work today, but v0.5.0 changes the behaviour of both (the server is now confined to its root; image Reads pass through), so pin an exact version if you script against them. Heuristic, and says so — the accuracy of fields, refs and intake: English-label matching with a confidence column, not a model. The desk TUI is a companion, not a product.

CI: Linux runs the full suite on Python 3.12–3.14 with every optional binary. The required macOS check is the degradation job — no extras, no binaries — so it proves carrel fails cleanly there, not that pandoc or tesseract paths work. Windows is advisory.

Security reports: see SECURITY.md — acknowledged within 7 days, fixed or explicitly declined within 30.

Two things carrel is not: a cloud document system (nothing leaves your disk, and there is no account), and a substitute for reading redaction or financial output before you rely on it.

Everything on the desk

Domain	Command	What it does
Convert & transform	carrel convert	Conversion across pdf, md, html, txt, docx, odt, epub, rtf, png/jpg/ico, json, xml, csv, plus xlsx → csv/json; the full SRC → target matrix is in carrel convert --help
	carrel ocr	Images and scanned PDFs → text, markdown, or a searchable PDF
	carrel edit	PDF merge/split/rotate/extract-pages, image resize/rotate/crop, text find-replace, json set/del
	carrel extract-images	Pull embedded images out of pdf, ico, and html
	carrel audiobook	Narrate txt/md/pdf and docx/odt/epub/rtf into mp3/ogg, chapters from markdown headings
Inspect & prove	carrel inspect	Metadata + per-type structure summary: sha256, pages, EXIF, json shape, csv dialect, docx paragraphs, xlsx sheets…
	carrel diff	Unified text diffs, structural json/csv diffs, pdf text diffs, image pixel diffs
	carrel thumb	Thumbnails for pdfs, images, and html
	carrel proof	Soft-proof against an ICC profile, with a ΔE summary
	carrel color	Dominant palette extraction, ICC conversion, contrast checks
The desk index	carrel index	SQLite FTS5 index of everything under a root (.carrel/carrel.db, versioned schema); --status reports stale rows
	carrel search	bm25-ranked full-text search with type and tag filters
	carrel tag	Tag files; find by tag
	carrel note	Sidecar notes on any file; real text annotations on PDFs
	carrel meta	Typed fields on files — vendor=Acme, total=1234.56, due=2026-10-01 — queried with meta find 'total>1000' 'due<2026-11', exported as a CSV of the folder
	carrel catalog	Export/import tags + notes + fields as JSON (move a desk, commit it next to a repo); status shows schema version and stale index rows
Read the documents	carrel fields	Vendor, invoice number, PO, dates, subtotal/tax/total, currency and IBAN out of invoices, receipts and statements — each with a confidence and the line it came from; --save records them as desk fields
	carrel refs	Reference numbers anywhere in a folder: invoice, PO, order, check, account, tracking, ticket, plus check-digit-verified IBAN, ABA routing, EIN, VAT, ISBN, GTIN, DOI, UPS, USPS. --tag links every document that shares one; --link shows the grouping
Email	carrel mail	.eml/.mbox are ordinary desk files (inspect, convert, index, search, pack, refs all read them, stdlib only). mail adds the rest: save attachments with digests, split a mailbox into messages, group messages into threads, convert Outlook .pst exports
Agents & context	carrel pack	Bundle files/trees into one LLM-ready document — md/xml/json; --query packs what the desk index ranks relevant, --since REF/--changed packs what git touched; include/exclude globs, .gitignore-aware (with ! negation), chunking, --dedupe-content, --outline, token estimates or exact counts (--tokenizer exact)
	carrel mcp	Serve the whole desk over MCP on stdio: 14 tools (search, pack, inspect, tag, note, index, convert, diff, redact, doctor, meta, fields, mail, refs) plus carrel://file/{path} and carrel://search/{query} resources
Housekeeping	carrel organize	Sort a folder by type/date/EXIF date — dry-run by default
	carrel dedupe	Exact (BLAKE2) and near (perceptual hash) duplicate detection
	carrel rename	Rename files from what they say — {date}_{vendor}_{ref}{ext} — dry-run first, collision-safe, and the desk's tags and notes follow the file
	carrel batch	Run any command over many files: parallel jobs, a resumable manifest, dry-run, per-file JSON records
	carrel watch	Watch a folder and run shell actions on file events — recursive, settle-wait for slow writers, polling for /mnt/c and network shares, done/error folders, a printable systemd or Task Scheduler unit
	carrel intake	The inbox in one command: read each document, name it, file it into YYYY/MM (or fiscal quarters), index it, record its fields and tag its references. Scans are OCRed into a searchable copy, the original is kept
	carrel redact	Pattern/PII redaction for text formats; true raster redaction for PDFs
	carrel sign	Visible PDF stamps, sha256 manifests, gpg-backed verify
	carrel form	Build html/pdf forms from JSON specs; list and fill AcroForm PDFs
The desk itself	carrel desk	A companion TUI — see below; needs the tui extra
	carrel doctor	What your environment enables today, with install hints for the rest
	carrel completion	Tab-completion scripts for bash, zsh, and fish

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).

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

Plugin	Gives Claude
carrel-inspect	/inspect, /diff, /search, /pack + a context-packing skill
carrel-convert	/convert, /ocr, /thumb, /edit, /extract-images, /audiobook + a batch doc-converter agent
carrel-organize	/organize, /dedupe, /tag, /note-file, /meta, /rename, /batch
carrel-finance	/refs, /fields — find and cross-link invoice, PO, IBAN, routing and tracking numbers; extract vendor, dates and totals from invoices, receipts and statements + a bookkeeper agent and an accounting-inbox skill
carrel-documents	/redact, /sign, /form, /proof, /color + a document-clerk agent (redact → verify → sign) and a redaction-and-provenance skill
carrel-mail	/mail — attachments, mbox split, threads, Outlook .pst via readpst; eml/mbox are desk file types + a mail-archive skill
carrel-watch	/watch-folder, /intake — file an inbox by what the documents say + a watch-automation recipe skill
carrel-agent	/index, /doctor, /catalog, /completion, a file-librarian agent, the carrel MCP server, and a hook that re-indexes files Claude writes
carrel-guard	A PreToolUse hook that turns the files Read cannot open — Office/ebook/RTF, spreadsheets, email — into text before it sees them, and PDFs into cheap text by default; images are left to Claude's vision. Plus a SessionStart hook that reports what carrel can do here

Install the CLI first (see Install) 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

carrel desk — browse the tree, inspect a file, run an action, search the index.

A companion to the CLI: 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/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 (the v0.1.0 record: cookbook runs, office and pack --query proofs)
• examples/cookbook/ — end-to-end recipes, from scan→searchable-notes to pack-what-matters
• docs/BRAND.md — palette, typography, logo usage, voice
• docs/HOW_THIS_WAS_BUILT.md — how this was built: the autonomous single-day build, from the primary sources

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