agentproto cron

agentproto cron add --schedule <cron-expr>
                    (--command <cmd> [--args <arg>...] [--cwd <dir>] [--timeout-ms <duration>]
                     | --adapter <slug> --prompt <text> [--cwd <dir>] [--model <id>]
                                       [--options-json <json|@file>]
                     | --target-session <id> --prompt <text>)
                    [--label <text>] [--once] [--json]
agentproto cron list   [--json]
agentproto cron remove <id>                    (aliases: delete, rm)
agentproto cron run    <id> [--json]

--timeout-ms accepts a duration string. Because the flag name already declares milliseconds, the value must be a bare integer or carry an ms suffix (30s and 5m are rejected).

Manage durable cron jobs on the daemon — run a command, spawn an agent, or re-prompt a live session on a schedule. Jobs persist to ~/.agentproto/cron-jobs.json and survive daemon restarts.

Requires a running daemon (serve.md or daemon.md); the verb drives the /cron HTTP routes.

Fires missed during downtime are not backfilled. A recurring job resumes from "now" after a restart rather than catching up on what it slept through.

ScheduleCopy Anchor Link

A 5-field cron expression in local time:

minute(0-59) hour(0-23) day-of-month(1-31) month(1-12) day-of-week(0-7, 0=Sun)

Jobs recur indefinitely by default. --once fires a single time, then deactivates the job (it stays listed, inactive).

Action kindsCopy Anchor Link

Exactly one per job — --command, --adapter, and --target-session are mutually exclusive, and passing none or more than one exits 2.

SubverbsCopy Anchor Link

addCopy Anchor Link

Creates a job via POST /cron and prints its id, schedule, recurrence, and next run.

listCopy Anchor Link

Lists every job via GET /cron — label, schedule, recurring/one-shot, active/inactive, next run, last run, and last result.

remove <id>Copy Anchor Link

Deletes a job via DELETE /cron/:id. Accepts delete and rm as aliases.

run <id>Copy Anchor Link

Fires a job now via POST /cron/:id/run, out of band, and reports the result.

A manual fire is the same fire the scheduler would have run, not a rehearsal: it records lastResult, and on a --once job it consumes the single fire — the job deactivates just as if its schedule had come round. A recurring job's nextRunAt is recomputed from its expression, so its cadence is unchanged.

ExamplesCopy Anchor Link

# One-shot smoke test a minute from now
agentproto cron add --schedule "* * * * *" --command echo --args hello --once

# Weekday-morning standup — a fresh agent session each time
agentproto cron add --schedule "0 9 * * 1-5" \
  --adapter claude-code --prompt "daily standup" --label "standup"

# Check in on a long-lived session every 15 minutes, in place
agentproto cron add --schedule "*/15 * * * *" \
  --target-session sess_abc123 --prompt "status?"

# Spawn an agent with a custom MCP server every 2 hours
agentproto cron add --schedule "0 */2 * * *" --adapter my-adapter \
  --prompt "health check" \
  --options-json '{"mcpServers":[{"name":"gateway","transport":"http","ref":"http://127.0.0.1:18790/mcp"}]}'

# Inspect, fire out of band, tear down
agentproto cron list --json
agentproto cron run    <id>
agentproto cron remove <id>

See alsoCopy Anchor Link

• serve.md — the daemon that owns the scheduler
• sessions.md — the sessions --adapter spawns and --target-session re-prompts
• policy.md — completion gates, the other way to drive work without watching it