carrel

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

Related MCP server: MCP Codebase RAG Server

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

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

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