{
  "title": "Cron vs Heartbeat: When to Use Each",
  "content": "Both heartbeats and cron jobs let you run tasks on a schedule. This guide helps you choose the right mechanism for your use case.\n\n## Quick Decision Guide\n\n| Use Case                             | Recommended         | Why                                      |\n| ------------------------------------ | ------------------- | ---------------------------------------- |\n| Check inbox every 30 min             | Heartbeat           | Batches with other checks, context-aware |\n| Send daily report at 9am sharp       | Cron (isolated)     | Exact timing needed                      |\n| Monitor calendar for upcoming events | Heartbeat           | Natural fit for periodic awareness       |\n| Run weekly deep analysis             | Cron (isolated)     | Standalone task, can use different model |\n| Remind me in 20 minutes              | Cron (main, `--at`) | One-shot with precise timing             |\n| Background project health check      | Heartbeat           | Piggybacks on existing cycle             |\n\n## Heartbeat: Periodic Awareness\n\nHeartbeats run in the **main session** at a regular interval (default: 30 min). They're designed for the agent to check on things and surface anything important.\n\n### When to use heartbeat\n\n* **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.\n* **Context-aware decisions**: The agent has full main-session context, so it can make smart decisions about what's urgent vs. what can wait.\n* **Conversational continuity**: Heartbeat runs share the same session, so the agent remembers recent conversations and can follow up naturally.\n* **Low-overhead monitoring**: One heartbeat replaces many small polling tasks.\n\n### Heartbeat advantages\n\n* **Batches multiple checks**: One agent turn can review inbox, calendar, and notifications together.\n* **Reduces API calls**: A single heartbeat is cheaper than 5 isolated cron jobs.\n* **Context-aware**: The agent knows what you've been working on and can prioritize accordingly.\n* **Smart suppression**: If nothing needs attention, the agent replies `HEARTBEAT_OK` and no message is delivered.\n* **Natural timing**: Drifts slightly based on queue load, which is fine for most monitoring.\n\n### Heartbeat example: HEARTBEAT.md checklist",
  "code_samples": [],
  "headings": [
    {
      "level": "h2",
      "text": "Quick Decision Guide",
      "id": "quick-decision-guide"
    },
    {
      "level": "h2",
      "text": "Heartbeat: Periodic Awareness",
      "id": "heartbeat:-periodic-awareness"
    },
    {
      "level": "h3",
      "text": "When to use heartbeat",
      "id": "when-to-use-heartbeat"
    },
    {
      "level": "h3",
      "text": "Heartbeat advantages",
      "id": "heartbeat-advantages"
    },
    {
      "level": "h3",
      "text": "Heartbeat example: HEARTBEAT.md checklist",
      "id": "heartbeat-example:-heartbeat.md-checklist"
    }
  ],
  "url": "llms-txt#cron-vs-heartbeat:-when-to-use-each",
  "links": []
}