MARKETPLACE — using the carrel plugins in Claude Code¶

This repo doubles as a Claude Code plugin marketplace: .claude-plugin/marketplace.json at the root declares seven plugins living under plugins/. The install flow below was executed on 2026-07-16 and re-validated with the seven-plugin catalog on 2026-09-04 (see TEST_REPORT.md for the proof runs).

Prerequisite: the carrel CLI on PATH¶

Every plugin is a thin wrapper that has Claude run the carrel CLI, so install it first:

uv tool install /path/to/this/repo     # puts `carrel` on PATH
carrel doctor                          # shows which optional binaries you have

(uv tool install — like pipx — installs the package into its own venv and links the carrel binary into ~/.local/bin.) Without it, every command falls back to telling you to install it or run uv run carrel ... from this repo, and the hooks stay silent.

Install flow¶

claude plugin validate .                                   # optional sanity check
claude plugin marketplace add coltonbearden/carrel
# ✔ Successfully added marketplace: carrel

claude plugin install carrel-inspect@carrel
# ✔ Successfully installed plugin: carrel-inspect@carrel (scope: user)

claude plugin list
# Installed plugins:
#
#   ❯ carrel-inspect@carrel
#     Version: 0.5.0
#     Scope: user
#     Status: ✔ enabled

Install any subset — the seven plugins are independent. In an interactive session the commands autocomplete by their short name (/inspect, /pack, /redact ...). In headless claude -p mode you must use the plugin-namespaced name:

claude -p "/carrel-inspect:inspect report.pdf" --allowedTools "Bash(carrel:*)"
claude -p "/carrel-documents:redact tests/fixtures/sample.txt" --allowedTools "Bash(carrel:*)"

The seven plugins¶

Every carrel CLI command has a slash command (24 slash commands across seven plugins; desk is interactive and mcp is served via .mcp.json); carrel mcp is reached through the MCP server instead and carrel desk is an interactive TUI.

Plugin	Slash commands	Also ships	What it gives Claude
carrel-convert	`/convert`, `/ocr`, `/thumb`, `/edit`, `/extract-images`, `/audiobook`	`doc-converter` agent — batch conversions with per-file verification via `carrel inspect`	Turn any supported file into another (pdf/md/html/txt/office/ebook/images), OCR scans, merge/split/rotate PDFs, resize/crop images, pull embedded images, narrate documents
carrel-inspect	`/inspect`, `/diff`, `/search`, `/pack`	`context-packing` skill — `--query`-first selection, `--since` for PRs, `--outline` orientation, `--tokenizer exact` budgeting	Know what a file is, compare two files (text/struct/pdf/image), full-text search the desk, build LLM context packs that fit
carrel-organize	`/organize`, `/dedupe`, `/tag`, `/note-file`, `/meta`, `/rename`, `/batch`	—	Sort a folder by type/date (dry-run first), find exact/near duplicates (report-only by default), tag, annotate and record typed fields on files, rename files from what they say (`{date}_{vendor}_{ref}{ext}`), run any command over many files with a resumable manifest
carrel-finance	`/refs`, `/fields`	`bookkeeper` agent (read → cross-reference → propose a filing plan, never applying it unasked), `accounting-inbox` skill	Find invoice, PO, order, check, IBAN, routing, VAT, ISBN and tracking numbers in any supported file (check digits verified), tag files with `ref:<kind>:<value>`, list the documents that share a reference; extract vendor, invoice number, dates, subtotal/tax/total and currency from invoices, receipts and statements with a confidence per field
carrel-documents	`/redact`, `/sign`, `/form`, `/proof`, `/color`	`document-clerk` agent (redact → verify → sign manifest → report; never overwrites without `--force`), `redaction-and-provenance` skill	Remove PII with true-raster PDF redaction, stamp/sign/verify, list and fill PDF forms or build HTML ones, soft-proof and color-manage images
carrel-mail	`/mail`	`mail-archive` skill — split → index → threads → attachments → cross-reference with `refs`	Save attachments (with sha256), split an mbox into dated `.eml` files, group messages into threads, convert Outlook `.pst` exports (readpst); `.eml`/`.mbox` are first-class desk files for inspect/convert/index/search/pack/refs and the Read guard
carrel-watch	`/watch-folder`, `/intake`	`watch-automation` skill — auto-thumb / auto-index / auto-convert drop-folder recipes	React to files landing in a folder
carrel-agent	`/index`, `/doctor`, `/catalog`, `/completion`	`file-librarian` agent, `agent-workflows` skill, the carrel MCP server (14 tools + `carrel://` resources), the PostToolUse reindex hook (below)	Keep a desk index current and healthy, know what the environment can do, export/import tags and notes, answer questions about a collection with citations
carrel-guard	—	`PreToolUse` Read guard + `SessionStart` capabilities hook (below)	Read docx/odt/epub/rtf, xlsx and eml/mbox as plain text — the formats `Read` cannot open — plus PDFs as cheap text by default; images stay pictures unless `CARREL_GUARD_OCR_IMAGES=1`. And start every session knowing carrel's capabilities

What the commands actually do: each command's markdown carries the generated --help of the command it wraps (regenerated by scripts/sync_plugins.py, drift fails CI) plus hand-written guidance, and tells Claude to run carrel ... --json, then interpret the result conversationally. Safety conventions baked in:

/organize and /dedupe always dry-run/report first — nothing moves or is deleted until you confirm (--apply, and for dedupe additionally --delete <policy>). /catalog import --replace is treated the same way.
Overwrites require an explicit ask (--force is never passed by default); /edit text refuses to rewrite a file without -i or -o.
Exit code 3 (missing optional binary) is relayed with its install hint; exit 4 means a missing/unsupported input.

The Read guard (carrel-guard)¶

Claude Code's Read tool understands text, images and PDFs (PDFs in pages ranges past ten pages) — and nothing else. carrel-guard registers a PreToolUse hook on Read that converts the formats it cannot open — .docx .odt .epub .rtf .xlsx .eml .mbox .mbx — to text with carrel into a cache directory, and rewrites the Read to the text file. PDFs are converted too, because page images cost far more tokens than the text (CARREL_GUARD_PDF_TEXT=0 keeps the visual Read when layout matters). Images are left alone: Read already shows Claude the picture, and OCR would replace a chart or a screenshot with a worse transcription (CARREL_GUARD_OCR_IMAGES=1 opts in). Claude reads the whole document as text in one call; the source is never modified, and the note says where it still is.

Before (no guard): Read tests/fixtures/sample.docx fails — the tool only handles text, images and PDFs, so Claude has to shell out and guess a conversion.

After (guard installed) — the hook-level transcript, executed 2026-09-04. Claude Code feeds the pending Read to the hook on stdin:

{"hook_event_name":"PreToolUse","tool_name":"Read",
 "tool_input":{"file_path":".../tests/fixtures/b.pdf","limit":40}}

and the hook answers (one line, shown wrapped):

{"hookSpecificOutput":{
  "hookEventName":"PreToolUse",
  "permissionDecision":"allow",
  "updatedInput":{"file_path":"~/.cache/carrel-guard/9cf65504…3683ca/b.txt","limit":40},
  "additionalContext":"carrel-guard: .../tests/fixtures/b.pdf was converted to text at ~/.cache/carrel-guard/9cf65504…3683ca/b.txt (135 chars). The original is untouched — Read .../tests/fixtures/b.pdf directly when layout, diagrams or images matter."}}

The Read then proceeds on b.txt — offset/limit pass through untouched — and Claude sees the additionalContext line explaining where the text came from. For anything else (a .md file, a file over 64 MiB, carrel missing, conversion failed, OCR not installed) the hook prints nothing and the normal Read happens.

The cache lives at ${XDG_CACHE_HOME:-$HOME/.cache}/carrel-guard/<sha256 of the absolute path>/<stem>.txt, is reused while newer than its source, and can be deleted at any time (rm -rf ~/.cache/carrel-guard). Details and tunables: plugins/carrel-guard/README.md.

The same plugin's SessionStart hook runs carrel doctor --json once and adds one paragraph of context, e.g.

carrel 0.5.0 is on PATH: 32 of 33 commands ok, 1 degraded, 0 unavailable. Run carrel doctor --json for the full table and carrel <cmd> --help before composing flags. Most useful missing binaries: readpst (sudo apt install pst-utils), edge-tts (pipx install edge-tts), piper (pipx install piper-tts).

Both hooks exit 0 on every path and are silent without carrel. Disable them with claude plugin disable carrel-guard.

The PostToolUse reindex hook (carrel-agent)¶

plugins/carrel-agent/hooks/hooks.json registers a PostToolUse hook on Write|Edit that runs scripts/reindex.sh. Effect: whenever Claude writes or edits a file in a project where you have already run carrel index (i.e. a .carrel/ desk db exists under the session cwd), the index row for that file is refreshed — carrel search stays current without re-indexing.

It is deliberately inert everywhere else. Every path out of the script is exit 0, under one second, and it does nothing unless all of these hold:

carrel is on PATH,
the hook payload names an existing file,
a .carrel/ directory exists under the session's cwd.

It never creates an index (--if-indexed), never blocks the session, and swallows degenerate payloads silently.

To disable it (without losing the librarian agent/skill), disable or uninstall the plugin that ships it:

claude plugin disable carrel-agent      # keep it installed, hook + MCP server off
claude plugin enable carrel-agent       # turn it back on

There is no per-hook toggle — hooks load with their plugin.

The MCP server (carrel-agent)¶

plugins/carrel-agent/.mcp.json registers a stdio MCP server:

{"mcpServers": {"carrel": {"command": "carrel", "args": ["mcp"]}}}

The server (pure stdlib JSON-RPC over stdio, protocol 2025-06-18) exposes fourteen tools and two resource templates:

Tool	Does
`carrel_search`	Full-text search of the desk index (`.carrel/carrel.db`) under `root`; needs a prior `carrel index`
`carrel_pack`	Pack a file/directory into LLM-ready context (tree + extracted text, budgets, `tree_only`)
`carrel_inspect`	Metadata for one file: detected type, size, mtime, sha256, per-type detail
`carrel_tag`	Add / remove / list tags on desk files
`carrel_note`	Add / list sidecar notes on desk files
`carrel_index`	Build or refresh the desk index (incremental)
`carrel_convert`	Convert a file to another supported type
`carrel_diff`	Compare two files (text / struct / pdf / image modes)
`carrel_redact`	Redact builtin or custom patterns from a text file or PDF
`carrel_doctor`	Environment capability report
`carrel_meta`	Set / get / list / remove typed fields on a desk file, or find files by conditions (`total>1000`, `due<2026-11-01`)
`carrel_fields`	Extract vendor, invoice number, dates, subtotal/tax/total, currency and IBAN from a document with a confidence per field; `save` writes them as desk fields
`carrel_mail`	Save an email's attachments into a directory, or group eml/mbox messages into threads
`carrel_refs`	Find reference numbers (invoice, PO, IBAN, routing, tracking, …) in a file or directory; tag files with them or group files by shared value

Resource template	Returns
`carrel://file/{path}`	The extracted text of a file — the same spine `pack` and `index` use
`carrel://search/{query}`	The desk-search hits for an FTS5 query

When the server is connected, Claude prefers these structured tools over shelling out for the same operations. The server works on the desk under the session's working directory (a root argument overrides) — run carrel index there first. The agent-workflows skill documents the same table for Claude.

Updating, uninstalling, removing¶

claude plugin update carrel-inspect          # re-pull from the marketplace source
claude plugin uninstall carrel-inspect       # alias: claude plugin remove
claude plugin marketplace update carrel      # refresh the marketplace itself
claude plugin marketplace remove carrel      # alias: rm — drops marketplace + its catalog

(Command names taken from claude plugin --help / claude plugin marketplace --help.)