Skip to main content

Cron vs Heartbeat: When to Use Each

Both heartbeats and cron jobs let you run tasks on a schedule. This guide helps you choose the right mechanism for your use case.

After you upgrade

Existing reminders, scheduled jobs, and heartbeat checklists keep working. You do not need to recreate them or change how you talk to WednesdayAI in chat. If a reminder you expected never arrived, ask whoever runs the Gateway to check wednesdayai cron list and wednesdayai task status --task cron-run.

What you should see

  • A scheduled reminder or nudge that has something to say arrives in the same chat you already use. Quiet check-ins (HEARTBEAT_OK / nothing to report) stay silent.
  • If WednesdayAI was mid-conversation when a reminder fired, only a reminder that is set to wait its turn (--wake next-heartbeat, or any other busy: delay turn) still arrives after a Gateway restart. A main-session reminder with --wake now may skip when the conversation is busy. Those skipped “now” reminders are not parked, so a restart does not bring them back.
  • An isolated heartbeat check-in reads only the plugin signal notes queued for your main chat, and it answers them in that check-in. Every other queued item stays put and waits for your next real message.
  • Isolated summaries, failure alerts, auto-disable notices, and wake-ups are ordinary scheduled turns. They do not start a separate heartbeat cycle.
Cron jobs import into the Gateway store on first start. Heartbeat skip reasons and isolated-session rules stay the same. Cron, heartbeat, and nudge are peer producers on agent.turn. Each enqueues its own turn. Cron does not require heartbeat config and does not call the heartbeat runner.

Quick Decision Guide

Scheduled isolated cron jobs still show up in chat the same way: a summary or nothing, depending on how you set delivery. Chat messages you send keep streaming as they arrive. Heartbeats are unchanged.

Heartbeat: Periodic Awareness

Heartbeats run against a configured session at a regular interval (default: 30 min). By default that is the main session. Set isolatedSession: true when the heartbeat should make the same delivery decision from the base session but run the model in a fresh :heartbeat sibling transcript.

When to use heartbeat

  • Multiple periodic checks: Instead of 5 separate cron jobs checking inbox, calendar, weather, notifications, and project status, a single heartbeat can batch all of these.
  • Context-aware decisions: The agent can use the configured session context, or a lightweight isolated heartbeat context when you want to avoid transcript churn.
  • Conversational continuity: Heartbeat delivery can still target the base conversation even when isolatedSession: true keeps heartbeat turns out of that transcript.
  • Low-overhead monitoring: One heartbeat replaces many small polling tasks.

Heartbeat advantages

  • Batches multiple checks: One agent turn can review inbox, calendar, and notifications together.
  • Reduces API calls: A single heartbeat is cheaper than 5 isolated cron jobs.
  • Context-aware: The agent knows what you’ve been working on and can prioritize accordingly.
  • Smart suppression: If nothing needs attention, the agent replies HEARTBEAT_OK and no message is delivered.
  • Natural timing: Drifts slightly based on queue load, which is fine for most monitoring.

Heartbeat example: HEARTBEAT.md checklist

The agent reads this on each heartbeat and handles all items in one turn.

Configuring heartbeat

See Heartbeat for full configuration.
Per-agent note: once any agents.list[] entry defines a heartbeat block, only those agents run heartbeats (isHeartbeatEnabledForAgent in src/infra/heartbeat-runner.config.ts) — an explicit block on one agent turns heartbeats off for every other agent.

Cron: Precise Scheduling

Cron jobs run at precise times and can run in isolated sessions without affecting main context. Recurring top-of-hour schedules are automatically spread by a deterministic per-job offset in a 0-5 minute window.

When to use cron

  • Exact timing required: “Send this at 9:00 AM every Monday” (not “sometime around 9”).
  • Standalone tasks: Tasks that don’t need conversational context.
  • Different model/thinking: Heavy analysis that warrants a more powerful model.
  • One-shot reminders: “Remind me in 20 minutes” with --at.
  • Noisy/frequent tasks: Tasks that would clutter main session history.
  • External triggers: Tasks that should run independently of whether the agent is otherwise active.

Cron advantages

  • Precise timing: 5-field or 6-field (seconds) cron expressions with timezone support.
  • Built-in load spreading: recurring top-of-hour schedules are staggered by up to 5 minutes by default.
  • Per-job control: override stagger with --stagger <duration> or force exact timing with --exact.
  • Session isolation: Runs in cron:<jobId> without polluting main history.
  • Model overrides: Use a cheaper or more powerful model per job.
  • Delivery control: Isolated jobs default to announce (summary); choose none as needed.
  • Immediate delivery: Announce mode posts directly without waiting for heartbeat.
  • No agent context needed: Runs even if main session is idle or compacted.
  • One-shot support: --at for precise future timestamps.

Cron example: Daily morning briefing

This runs at exactly 7:00 AM New York time, uses Opus for quality, and announces a summary directly to WhatsApp.

Cron example: One-shot reminder

See Cron jobs for full CLI reference.

Decision Flowchart

Combining Both

The most efficient setup uses both:
  1. Heartbeat handles routine monitoring (inbox, calendar, notifications) in one batched turn every 30 minutes.
  2. Cron handles precise schedules (daily reports, weekly reviews) and one-shot reminders.

Example: Efficient automation setup

HEARTBEAT.md (checked every 30 min):
Cron jobs (precise timing):

Lobster: Deterministic workflows with approvals

Lobster is the workflow runtime for multi-step tool pipelines that need deterministic execution and explicit approvals. Use it when the task is more than a single agent turn, and you want a resumable workflow with human checkpoints.

When Lobster fits

  • Multi-step automation: You need a fixed pipeline of tool calls, not a one-off prompt.
  • Approval gates: Side effects should pause until you approve, then resume.
  • Resumable runs: Continue a paused workflow without re-running earlier steps.

How it pairs with heartbeat and cron

  • Heartbeat/cron decide when a run happens.
  • Lobster defines what steps happen once the run starts.
For scheduled workflows, use cron or heartbeat to trigger an agent turn that calls Lobster. For ad-hoc workflows, call Lobster directly.

Operational notes (from the code)

  • Lobster runs as a local subprocess (lobster CLI) in tool mode and returns a JSON envelope.
  • If the tool returns needs_approval, you resume with a resumeToken and approve flag.
  • The tool is an optional plugin; enable it additively via tools.alsoAllow: ["lobster"] (recommended).
  • Lobster expects the lobster CLI to be available on PATH.
See Lobster for full usage and examples.

Main Session vs Isolated Session

Both heartbeat and cron can interact with the main session, but differently:

When to use main session cron

Use --session main with --system-event when you want:
  • The reminder/event to run as an agent.turn (kind cron) on the main session
  • The turn to run immediately (--wake now) or to deliver on the next main-lane idle (--wake next-heartbeat: publishes immediately when the lane is idle at fire time, otherwise parks and runs once the lane frees up — not a heartbeat tick)
  • No separate isolated run

When to use isolated cron

Use --session isolated when you want:
  • A clean slate without prior context
  • Different model or thinking settings
  • Announce summaries directly to a channel
  • History that doesn’t clutter main session

Nudge and wake-gate jobs

Both heartbeat and cron can run a cheap check that wakes the agent’s main persona only when the check finds something worth acting on — the nudge contract. Use this when “is there anything to do?” is cheap to answer but the response is expensive. A heartbeat wake-gate turns the periodic heartbeat into a gate: it runs the cheap check first and skips the persona turn (reason wake-gate-empty) when the check is negative. See Heartbeat. A cron wake-gate job runs at a precise schedule, fires the same kind of cheap check, and nudges the main session only on a positive result. The job uses sessionTarget: "main" with a wakeGate payload (a forward-only cron store kind — ADR 0015):
On a positive gate the cron runner nudges the main session with the gate text (agent.turn kind nudge); on a negative gate the run is recorded as skipped and no persona turn happens. Like every nudge, the result is silent-unless-it-decides; a nudge against a busy main session parks (busy: delay) and delivers on lane idle rather than being dropped, and nudges are not subject to active-hours gating. Cron also forwards job cancellation into wake-gate checks and isolated runs, but not into requestNudge — a published nudge follows the nudge lifecycle and is not cancelled by job abort. If a scheduled or manual run is stopped, command/model checks are cancelled with the job instead of continuing in the background. See Cron jobs for the full payload reference.

Cost Considerations

Tips:
  • Keep HEARTBEAT.md small to minimize token overhead.
  • Batch similar checks into heartbeat instead of multiple cron jobs.
  • Use target: "none" on heartbeat if you only want internal processing.
  • Use isolated cron with a cheaper model for routine tasks.
  • Heartbeat - full heartbeat configuration
  • Cron jobs - full cron CLI and API reference
  • System - system events + heartbeat controls