carrel

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.

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.

Related MCP server: local-mcp

Quickstart

Requires Python ≥ 3.12 and uv. No checkout needed:

uv tool install git+https://github.com/FirstCastSolutions423/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 table

Add --json to any of these and you get machine-readable output on stable exit codes — that's the whole agent contract.

The marketplace

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

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 (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

License

MIT © Colton Bearden