Skip to main content
The heartbeat system gives IronClaw agency between conversations. Every 30 minutes (by default), it reads HEARTBEAT.md from the workspace and executes a checklist of proactive tasks — without you having to ask.
You can setup how often the agent checks the heartbeat list

​
What Heartbeat Does

On each heartbeat tick:
  1. Reads HEARTBEAT.md from the workspace root
  2. Runs the checklist items as an agent job
  3. If the job produces findings or output, sends a notification to the configured channel
  4. Records the run in the heartbeat_state table
If HEARTBEAT.md does not exist or is empty, the tick is a no-op. The heartbeat job runs through the full agent loop — LLM reasoning, tool calls, safety layer — with the same capabilities as a manually triggered job.

​
HEARTBEAT.md Format

Write HEARTBEAT.md as a checklist of tasks. The agent reads this as its instructions for each periodic run:
The agent interprets the checklist and executes each item using available tools. Conditional items (“run only on Mondays”) are evaluated by the LLM using the current date.

​
Notification Behavior

After each tick, if the job produces output that warrants user attention, the heartbeat system sends a notification to the configured channel. If nothing actionable was found, no notification is sent — heartbeat is designed to be quiet unless it has something useful to say. Findings are also written to memory at heartbeat/latest.md (if your HEARTBEAT.md instructs this), making them searchable in future sessions.

​
Configuration

Set HEARTBEAT_INTERVAL_SECS=3600 (1 hour) or higher if the heartbeat job is too frequent for your LLM API rate limits or budget. The heartbeat runs as a normal job and consumes tokens.

​
Writing HEARTBEAT.md

Ask the agent to create or update the heartbeat checklist:
Or edit the file manually:

​
Example HEARTBEAT.md Files

​
Minimal — Inbox Monitor

​
Developer Workflow

​
Personal Assistant

​
Heartbeat vs Routines

Heartbeat and cron routines serve similar purposes but differ in design: Use heartbeat for a unified set of periodic checks. Use cron routines when you need different schedules for different tasks, or when tasks should run independently.

​
Troubleshooting

  • Verify HEARTBEAT_ENABLED=true in your configuration
  • Check startup logs for heartbeat to confirm the system started
  • Confirm HEARTBEAT_INTERVAL_SECS is set to a reasonable value
  • Verify HEARTBEAT.md exists in the workspace root via memory_read path="HEARTBEAT.md"
  • Update HEARTBEAT.md to add a condition: “only notify if there are actionable items”
  • Increase HEARTBEAT_INTERVAL_SECS to reduce frequency
  • Make checklist items more specific so the agent doesn’t over-report
  • Simplify HEARTBEAT.md — fewer checklist items mean fewer LLM calls
  • Increase HEARTBEAT_INTERVAL_SECS to reduce frequency
  • Add guardrails-style instructions to HEARTBEAT.md: “Use at most 5 tool calls per run”