Docs › Claude Code: Routines, headless runs and hooks

Claude Code: Routines, headless runs and hooks

RunVouch watches Claude Code agents that run without you: Routines, claude -p in cron, desktop scheduled tasks. The plugin uses Claude Code hooks to report the start, every tool call, and the stop — including tokens and cost read from the transcript.

On this page

Install the plugin
Wire a Routine or cron job
Evidence: prove the task happened
Cost caps and retry storms
Ask your agents about each other (MCP)

Install the plugin

/plugin marketplace add runvouch/claude-plugin
/plugin install runvouch

Or from a checkout: claude --plugin-dir ./integrations/claude-code-plugin. The plugin is a no-op in interactive sessions — it only reports when RUNVOUCH_AGENT is set.

Wire a Routine or cron job

# once: register the agent
rv agent nightly-report --cadence 24h --cap-run-cost 2 --evidence

# in the Routine / cron environment
export RUNVOUCH_KEY=rv_…
export RUNVOUCH_AGENT=nightly-report
export RUNVOUCH_EVIDENCE='{"report":{"type":"url","url":"https://example.com/reports/latest.html"}}'
claude -p "Generate tonight's report and publish it" --dangerously-skip-permissions

What gets reported: SessionStart → run start · PostToolUse → tool name + input hash + error flag (retry-storm and budget checks run on every call) · Stop → run end with tokens and cost summed from the transcript, plus your evidence.

Evidence: prove the task happened

Evidence turns "exit 0" into "done". Three forms:

URL — {"type":"url","url":"…","expect":200}, checked by RunVouch after the run.
File — with rv run --evidence-file PATH: the file must exist, be non-empty and have changed during the run. Checked on your machine; only true/false is sent.
Boolean — your own assertion: {"rows_inserted": true}.

If --evidence is set on the agent and a run ends "ok" without passing evidence, you get a NO_EVIDENCE alert.

Cost caps and retry storms

--cap-run-cost 2 and --cap-day-cost 10 alert the moment a run or a day crosses the line; combine with rv agent … --pause in your alert webhook to stop the schedule. Retry storms fire when the same tool is called with an identical input hash 8+ times in one run (configurable). Cost is computed from transcript usage with current Anthropic list prices; override with RUNVOUCH_COST / RUNVOUCH_TOKENS if you meter elsewhere.

Ask your agents about each other (MCP)

claude mcp add runvouch -e RUNVOUCH_KEY=rv_… -- python3 runvouch_mcp.py

Tools: runvouch_status, runvouch_alerts, runvouch_ack, runvouch_runs, runvouch_run_start, runvouch_run_end. A morning agent can refuse to build on last night's output if last night is UNPROVEN. See MCP docs.

Need a key? Get one free · Stuck? [email protected]