agent-workflows

Agent workflows with carrel

Patterns for wiring carrel and Claude Code together into pipelines. Run carrel doctor --json first to see what the environment supports (or install the carrel-guard plugin, whose SessionStart hook reports it), and --help on any carrel command before scripting it.

Pattern: watch + claude -p pipeline

React to new files with a headless Claude turn. Example — summarize every PDF dropped into a folder:

carrel watch ~/inbox --on created --glob '*.pdf' \
  --run 'sh -c "carrel convert {path} --to txt -o /tmp/drop.txt --force && claude -p \"Summarize /tmp/drop.txt in 5 bullets\" >> ~/inbox/summaries.md"'

Notes: keep the claude -p prompt self-contained; append results to a log/markdown file; test with --once --timeout 60 before leaving it running; bound each action with --action-timeout.

Pattern: index-then-ask loop

For question-answering over a collection, keep one desk index and reuse it:

carrel --json --root ~/papers index          # incremental, cheap to re-run
carrel --json --root ~/papers search 'transformer AND survey'
carrel --root ~/papers pack ~/papers --query 'transformer AND survey' --top 10 -o ctx.md

Feed the hit paths to Claude (or the file-librarian agent in this plugin) rather than packing the whole corpus — search first, read the top hits, cite paths. pack --query is the one-step version. Narrow a search with the desk's own facts: --tag ref:invoice:inv-2026-0042 (written by carrel refs --tag) or --meta 'total>1000' (fields from carrel meta set). carrel catalog status tells you when the index is stale; carrel catalog export backs up tags and notes.

Pattern: desk over MCP

This plugin ships a carrel MCP server (carrel mcp, stdio, pure stdlib) via .mcp.json. When it is connected, prefer its structured tools over shelling out for the same operations. The server works on the desk under the session's working directory (the root argument narrows it to a subdirectory); run carrel index there first for search-backed tools.