carrel desk — browse the tree, inspect a file, run an action, search the index.
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.
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, md, images, html, json, xml, csv — with 24 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.
| Domain | Command | What it does |
|---|---|---|
| Convert & transform | carrel convert |
Any-to-any conversion across pdf, md, html, txt, png/jpg/ico, json, xml, csv |
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 into mp3/ogg, chapters from markdown headings | |
| Inspect & prove | carrel inspect |
Metadata + per-type structure summary: sha256, pages, EXIF, json shape, csv dialect… |
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, portable) |
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 | |
| Agents & context | carrel pack |
Bundle files/trees into one LLM-ready document — md/xml/json, include/exclude globs, .gitignore-aware, chunking, token estimates |
carrel mcp |
Serve search/pack/inspect as an MCP server on stdio | |
| 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 watch |
Watch a folder and run shell actions on file events | |
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 |
The flagship TUI — see below |
carrel doctor |
What your environment enables today, with install hints for the rest |
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.
Requires Python ≥ 3.12 and uv. No checkout needed:
uv tool install carrel # or: pipx install carrel — puts `carrel` on your PATH
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 index . && carrel search "marginal notes" # FTS5 over your whole desk
carrel pack src/ --format xml -o context.xml --stats # LLM-ready context + token tableAdd --json to any of these and you get machine-readable output on stable exit codes — that's the whole agent contract.
This repo is also a Claude Code plugin marketplace: five plugins whose slash commands, agents, skills, and hooks all delegate to the CLI above.
claude plugin marketplace add FirstCastSolutions423/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, /audiobook + a batch doc-converter agent |
carrel-organize |
/organize, /dedupe, /tag, /note-file |
carrel-watch |
/watch-folder + a watch-automation recipe skill |
carrel-agent |
A file-librarian agent, the carrel MCP server, and a hook that re-indexes files Claude writes |
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.
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.
- 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 (501 tests, 7 cookbook runs)
- examples/cookbook/ — nine end-to-end recipes, from scan→searchable-notes to markdown→audiobook
- docs/BRAND.md — palette, typography, logo usage, voice
MIT © Colton Bearden
- 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