clawdbot/docs/cron-jobs.md

summary, read_when

summary	read_when
Cron jobs + wakeups for the Gateway scheduler	Scheduling background jobs or wakeups Wiring automation that should run with or alongside heartbeats

Cron jobs (Gateway scheduler)

Cron runs inside the Gateway and schedules background work so Clawdbot can wake itself up, run isolated agent jobs, and deliver reminders on time.

Update checklist (internal)

• Audit cron + heartbeat behavior in code
• Rewrite cron doc as user-facing feature
• Update heartbeat docs + templates
• Update cron links in docs
• Update changelog
• Run full gate (lint/build/test/docs)

What cron is

• Gateway-owned scheduler that persists jobs under ~/.clawdbot/cron/.
• Two execution modes:
  • Main session jobs enqueue System: events and rely on the heartbeat runner.
  • Isolated jobs run a dedicated agent turn in cron:<jobId> sessions.
• Wakeups are first-class: a job can trigger the next heartbeat or run it now.

When to use it

• Recurring reminders: “every weekday at 7:30” or “every 2h.”
• Background chores: summarize inboxes, check dashboards, watch logs.
• Automation that should not pollute the main chat history.
• Scheduled wakeups that drive the heartbeat pipeline.

Schedules

Cron supports three schedule kinds:

• at: one-shot timestamp in ms.
• every: fixed interval (ms).
• cron: 5-field cron expression, optional IANA timezone.

Cron expressions use croner under the hood. If a timezone is omitted, the server’s local timezone is used.

Job types

Main session jobs

Main jobs enqueue a system event and optionally wake the heartbeat runner. They must use payload.kind = "systemEvent".

• wakeMode: "next-heartbeat" (default): the event waits for the next scheduled heartbeat.
• wakeMode: "now": the event triggers an immediate heartbeat run.

Isolated jobs

Isolated jobs run a dedicated agent turn in session cron:<jobId> and can optionally deliver a message.

Key behaviors:

• Prompt is prefixed with [cron:<jobId> <job name>] for traceability.
• A summary is posted to the main session with prefix Cron (or isolation.postToMainPrefix).
• wakeMode: "now" triggers an immediate heartbeat after posting the summary.
• payload.deliver: true sends output to a provider; otherwise it stays internal.

Storage & history

• Job store: ~/.clawdbot/cron/jobs.json (JSON, Gateway-managed).
• Run history: ~/.clawdbot/cron/runs/<jobId>.jsonl (JSONL, auto-pruned).
• Override store path: cron.store in config.

Configuration

{
  cron: {
    enabled: true,                // default true
    store: "~/.clawdbot/cron/jobs.json",
    maxConcurrentRuns: 1           // default 1
  }
}

Disable cron entirely:

• cron.enabled: false (config)
• or CLAWDBOT_SKIP_CRON=1 (env)

CLI quickstart

One-shot reminder (main session, wake immediately):

clawdbot cron add \
  --name "Calendar check" \
  --at "20m" \
  --session main \
  --system-event "Next heartbeat: check calendar." \
  --wake now

Recurring isolated job (deliver to WhatsApp):

clawdbot cron add \
  --name "Morning status" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize inbox + calendar for today." \
  --deliver \
  --provider whatsapp \
  --to "+15551234567"

Manual run (debug):

clawdbot cron run <jobId> --force

Run history:

clawdbot cron runs --id <jobId> --limit 50

Immediate wake without creating a job:

clawdbot wake --mode now --text "Next heartbeat: check battery."

API surface (Gateway)

• cron.list, cron.status, cron.add, cron.update, cron.remove
• cron.run (force or due), cron.runs
• wake (enqueue system event + optional heartbeat)

Tips

• Use main session jobs when you want the heartbeat prompt + existing context.
• Use isolated jobs for noisy, frequent, or long-running work.
• Keep messages short; cron turns are full agent runs and can burn tokens.