Docs › Claude Code scheduled task monitoring with RunVouch
Claude Code scheduled task monitoring with RunVouch
Claude Code scheduled task monitoring for the three ways Claude runs without you: cloud Routines (/schedule), Desktop scheduled tasks, and claude -p from cron. The docs say it themselves: a green status in the run list does not mean the task in your prompt succeeded. RunVouch checks the outcome from outside.
How it runs on Claude Code scheduled tasks
For claude -p on a server, wrap the command with rv run and require the file the prompt is supposed to write. For Routines and Desktop tasks, install the RunVouch plugin; its hooks report the start, each tool call and the stop with cost from the transcript, so the run exists in RunVouch even when it never wrote anything.
Store the key
On a server: RUNVOUCH_KEY in the cron environment. In a Routine: an environment variable on the routine's cloud environment (note that environment variables there are visible to anyone who uses that environment). On Desktop: the user's shell environment or ~/.claude/settings.json env block.
Wrap the job
# once: the agent, its cadence, and what counts as done
rv agent nightly-changelog --cadence 24h --grace 2h --cap-run-cost 3 --evidence
# crontab on the machine that runs headless Claude Code (jitter-proof: not :00)
7 2 * * * cd /srv/repo && rv run nightly-changelog --evidence-file out/CHANGELOG-draft.md --log out/claude.log \
-- claude -p "$(cat prompts/changelog.md)" --dangerously-skip-permissions --max-turns 30
# Routine or Desktop task instead: same agent, reported by the plugin's hooks
export RUNVOUCH_AGENT=nightly-changelog
export RUNVOUCH_EVIDENCE='{"draft":{"type":"file","path":"out/CHANGELOG-draft.md"}}'rv fails open: if RunVouch is unreachable the job still runs and you get one warning line.
Register the cadence and caps
rv agent nightly-report --cadence 24h --grace 30m --max-runtime 1h --evidence --cap-run-cost 2
Register the agent once, from anywhere with the key. Cadence is what turns a schedule that stopped into an alert; --evidence makes a run without evidence a failure; the caps pause the agent when it overspends.
What goes silent on Claude Code scheduled tasks
- Routines: runs may start a few minutes after the scheduled time (stagger), and the minimum interval is one hour. Set grace to two hours and cadence to the real cadence; MISSED then means the routine did not run, not that it ran late.
- Desktop tasks: if the computer sleeps through the time, the run is skipped; on wake, exactly one catch-up run happens for the most recent missed time and older ones are discarded. A daily task that missed six days runs once.
- A run that hit
--max-turns, was denied a tool, or could not reach a domain outside the environment's allowlist (403,x-deny-reason: host_not_allowed) still exits; only the missing evidence file says it did not do the job. - Cost: the plugin reads tokens from the transcript; a run that loops on the same tool call is RETRY_STORM before it is a bill.
What Claude Code scheduled tasks does not tell you
The Claude Code documentation states that a green status in a Routine's run list means the session started and exited without an infrastructure error, and that it does not mean the task in your prompt succeeded; blocked network requests, missing connector tools and task-level failures surface in the transcript, not in the status. Desktop scheduled tasks show a notification when a task fires or a catch-up run starts, and list skipped runs in the task's history; nothing is sent when a run that should have happened did not. Headless claude -p in cron has exactly what cron has: an exit code and local mail.
What RunVouch detects
| Alert | What it means here |
|---|---|
| MISSED | cadence plus grace passed and no run started |
| FAILED | non-zero exit or a reported failure, with the stderr excerpt |
| NO_EVIDENCE | the run said ok but the file, URL or assertion you required is missing |
| STALLED | a run started and never ended within max runtime |
| RETRY_STORM | the same tool called with identical input many times in one run |
| BUDGET_RUN / BUDGET_DAY | cost cap crossed; the agent is paused until you resume it |
| DRIFT | duration or output size far off its 7-run baseline |
Set up in two minutes
- Get a free key (3 agents, no card) and store it where this page says.
- wrap the job: copy the snippet above into the scheduled job.
- Register the cadence once:
rv agent nightly-report --cadence 24h --grace 30m --evidence, or let the first run create the agent and set the cadence on the dashboard. - Send one test alert:
curl -X POST https://api.runvouch.com/v1/settings/test-alert -H "X-API-Key: $RUNVOUCH_KEY". The next missed, failed or empty run reaches the same channels.
Need a key? Get a free key · Stuck? contact