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: 
# Heartbeat Checklist

## Daily Tasks
- [ ] Check memory at daily/ for yesterday's notes. If missing, remind the user.
- [ ] Search memory for any items tagged as "follow-up" or "urgent" and list them.
- [ ] Read ops/stuck-jobs.md if it exists and summarize any unresolved incidents.

## Weekly Tasks (run only on Mondays)
- [ ] Summarize the week's daily notes into a weekly summary at weekly/<date>.md
- [ ] Check for any routines that haven't run in the past 7 days and flag them.

## Always
- [ ] If any of the above produce findings, write a summary to memory at heartbeat/latest.md
- [ ] Only notify the user if there are actionable items — do not send empty pings.
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

# Enable heartbeat (default: true)
HEARTBEAT_ENABLED=true

# Interval between ticks in seconds (default: 1800 = 30 minutes)
HEARTBEAT_INTERVAL_SECS=1800

# Channel to send notifications to
HEARTBEAT_NOTIFY_CHANNEL=tui     # tui, web, telegram, webhook

# User ID to notify
HEARTBEAT_NOTIFY_USER=default
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: 
Write HEARTBEAT.md with tasks to check my inbox/ folder every 30 minutes
and summarize any new items.
Or edit the file manually: 
memory_write path="HEARTBEAT.md" content="
# Heartbeat Checklist

- [ ] List all memory documents in inbox/ — if any exist, summarize and move to processed/
- [ ] Check if daily/<today>.md exists — if not, create a daily entry template
- [ ] Only notify if inbox/ had items or daily notes were missing
"

​
Example HEARTBEAT.md Files

​
Minimal — Inbox Monitor

# Heartbeat

- [ ] Check inbox/ for new documents. Process and move to processed/. Notify only if items were found.

​
Developer Workflow

# Heartbeat Checklist

## Checks
- [ ] Read ops/incidents/ — summarize any open incidents older than 24 hours
- [ ] Check for stuck jobs in the last hour
- [ ] Look for daily/<today>.md — create it with a timestamp if missing

## Output
- [ ] Write findings to heartbeat/latest.md
- [ ] Notify only if there are open incidents or stuck jobs

​
Personal Assistant

# Heartbeat

- [ ] Search memory for items tagged "reminder" or "todo"
- [ ] Check if any items are due today based on their content
- [ ] Summarize time-sensitive items and notify
- [ ] Do not notify if nothing is due

​
Heartbeat vs Routines

Heartbeat and cron routines serve similar purposes but differ in design:
FeatureHeartbeatCron Routine
ConfigurationSingle HEARTBEAT.md filePer-routine configuration
ScheduleFixed global intervalCustom per-routine cron expression
ScopeSingle checklist jobMultiple independent jobs
ComplexitySimple — edit one fileFlexible — manage multiple routines
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”