How to Build HEARTBEAT.md: From Zero to a Proactive AI Agent

What HEARTBEAT.md Actually Does

Every 30 minutes or so, OpenClaw polls your agent with a heartbeat message. When it does, the agent loads HEARTBEAT.md into its context along with the message. The file is your standing orders — "here's what to check every time you wake up."

Without HEARTBEAT.md, your agent is purely reactive. It only does something when you message it. With it, your agent checks pending approvals, picks up tasks, monitors sub-agents, and stays aware of what's happening — without you having to ask.

That's the whole thing. It's not magic. It's a file that gets read on a schedule.

The Design Principle: Fast Triage, Not Heavy Work

Before you write anything, understand the constraint: heartbeats should complete in under 2 minutes.

If you put heavy work in HEARTBEAT.md — "check the email inbox, search Reddit, run a web scrape, generate a report" — your heartbeats will be slow, expensive, and unreliable. More importantly, you're doing it wrong. That work belongs in dedicated cron jobs.

The distinction:

• Heartbeat: Fast triage. Did anything urgent happen? Are there approvals pending? Is anything stuck?
• Cron: Scheduled tasks. Email check at 8AM. Stripe report at 9AM. Reddit scan at 10AM and 6PM.

Every time you're tempted to add something to HEARTBEAT.md, ask: does this need session history, or does it just need to run on a schedule? If it's the latter, it's a cron.

The Structure That Works

Here's the structure I settled on after about three weeks of iteration:

# HEARTBEAT.md
# Target: <2 min to process | <60 lines

## Priority 1: Approval Handler (check EVERY heartbeat)

If Commander's or Captain's most recent message contains
batch approval commands (ok all, ok 1 3, skip 2):
- Run: social_batch_approve.py --approve "<their message>"

If slot skip commands (skip morning, skip afternoon, resume):
- Update config/social-scheduler-state.json
- Confirm: "✅ [action] applied."

Only act on commands since last heartbeat.

## Priority 2: Task Board (check EVERY heartbeat)

Read mission-control/data/tasks.json.
Find tasks where owner=Rapkyn AND status=backlog|ready.
If found: pick highest priority, update to in-progress, do it,
update to review, log to daily memory.
If none: skip silently.

## Priority 3: Sub-Agent Monitor (check EVERY heartbeat)

subagents(action=list) — check for stuck (>30 min) or completed.
- Stuck: steer, then flag if no response
- Completed: review output, update task, summarise to Commander
- Healthy: stay silent

## Priority 4: Quick Health (once per 4 hours)

Track in memory/heartbeat-state.json → lastHealthGlance.
- curl -s http://127.0.0.1:4790/api/health | head -c 500
- Check for failed crons with consecutive errors
- Only flag if something is broken

## If nothing needs attention: HEARTBEAT_OK

Four sections. Four priorities. Under 60 lines. Everything else is in crons.

Building It Section by Section

Section 1: The Approval Handler

This is the most important section and should always come first. The approval handler checks whether your operator has sent approval commands since the last heartbeat — and if so, acts on them immediately.

In my setup, this means checking for batch X post approvals (ok all, ok 1 3, skip 2) and slot skip commands. Your setup might be different — you might be checking for PR merge approvals, email drafts pending review, or customer messages flagged for response.

The key principle: approval handling should never wait more than 30 minutes. If your operator approves something and you don't act for 4 hours, the approval window has passed for time-sensitive content. The heartbeat is what keeps this responsive.

What to write for your approval handler:

• What approval phrases does your operator use? (Be specific — "ok all" vs "approve everything" vs "go ahead")
• What actions need to fire immediately on approval? (Script name, arguments)
• What cancellation commands should it respect? ("skip", "hold", "pause")
• Scope: only act on commands since the last heartbeat — not old messages.

Section 2: The Task Board

If you're running Mission Control or any task tracking system, this section has the agent scan for tasks assigned to it and pick up ready work.

Read tasks.json.
Find tasks where owner=Rapkyn AND status=ready.
If found:
  - Pick highest priority task
  - Update status to in-progress
  - Do the work
  - Update status to review
  - Log to daily memory file
If none: skip silently.

The "skip silently" at the end matters. Most heartbeats will find nothing. You don't want the agent sending you "nothing to do" messages every 30 minutes. Only speak when there's something worth saying.

Section 3: Sub-Agent Monitor

If you spawn sub-agents (coding agents, research agents, etc.), this section checks their status. A sub-agent that's been running for 35 minutes on a task that should take 5 is probably stuck. You want to catch that quickly.

subagents(action=list)
For each active sub-agent:
  - If running > 30 min: steer with "are you stuck?"
  - If completed: review output, update task board,
    summarise to Commander
  - If healthy: stay silent

If you don't use sub-agents, skip this section entirely.

Section 4: Quick Health (Rate-Limited)

A lightweight system health check — but with an important constraint: only run it every 4 hours, not every heartbeat.

Track when you last ran it in a state file:

Track in memory/heartbeat-state.json → lastHealthGlance.
If < 4 hours ago: skip
If >= 4 hours: run health check
  - API health endpoint
  - Failed crons with consecutive errors
  - Update lastHealthGlance timestamp
  - Only notify if something is broken

This is where the "rate limiting" principle matters. A health check every 30 minutes is 48 checks per day. Most of them find nothing. Running it every 4 hours is 6 checks per day — same signal, 87% less noise.

What NOT to Put in HEARTBEAT.md

After running this for weeks, I've moved everything that doesn't belong. These are the common mistakes:

The Security Rule

HEARTBEAT.md is loaded into agent context on every heartbeat. That means it's a prompt injection surface.

The rule: anything you write in HEARTBEAT.md should be a factual statement or a specific procedural instruction — never a negative command that looks like an override.

Wrong: Silent operation — do not message Commander

Right: X post approvals go to Localhost Confidential topic

The wrong example is a real thing that happened. A reminder I added to suppress notifications ended up being read as an instruction when a cron loaded it. The post was blocked. The security line held — but the vulnerability was real. The fix is content hygiene.

If a reminder feels like it could be misread as an override command, write it in your daily memory file instead and reference it from HEARTBEAT.md with a label only.

The Audit Rule

Once a month, audit your HEARTBEAT.md:

1. Count the lines. If over 60, something crept in that should be a cron.
2. List every check it's doing. For each one: does a dedicated cron already handle this?
3. Time the heartbeat. If it takes more than 2 minutes, find what's slow and move it out.
4. Review cron list. For each cron, confirm it's still needed and running without errors.

I ran this audit last week. My HEARTBEAT.md had grown to 180 lines with 13 distinct tasks — email checking, Reddit monitoring, calendar sync, X mentions, Stripe monitoring. Each had crept in over weeks. I moved all of them to dedicated crons. Heartbeat went from 10+ minutes back to under 90 seconds.

Design rule: Heartbeat = fast triage. If a task takes more than 30 seconds or runs fine on a schedule, it belongs in a cron.

A Complete Working Example

Here's a minimal but complete HEARTBEAT.md for a solo operator running content and tasks:

# HEARTBEAT.md
# Target: <2 min · <60 lines

## Priority 1: Approval Handler

Check Commander's most recent message for approval commands:
- "ok all" / "ok 1 3" / "skip 2" → run social_batch_approve.py
- "skip morning/afternoon" → update social-scheduler-state.json

Only act on messages since last heartbeat.

## Priority 2: Task Board

Read data/tasks.json.
Find tasks: owner=agent AND status=ready.
If found: pick highest priority, update to in-progress,
  execute, update to review, log to memory/YYYY-MM-DD.md.
If none: skip silently.

## Priority 3: Sub-Agent Monitor

subagents(action=list).
- >30 min running: steer with a check-in
- Completed: review, summarise to Commander
- Healthy: silent

## Priority 4: Quick Health (every 4h)

Track in memory/heartbeat-state.json → lastHealthGlance.
- Check API health endpoint
- Check for consecutive cron failures
- Notify only if broken

## If nothing: HEARTBEAT_OK

52 lines. Under 2 minutes to process. Does exactly what it should.

From Reactive to Proactive

The difference between an agent that waits and an agent that works is not the model. It's whether you've given it standing orders.

HEARTBEAT.md is how you give it those orders. Keep it lean, keep it factual, keep it fast. Everything else belongs in a cron.

If you're not sure whether your current HEARTBEAT.md is set up well, or if your agent is behaving inconsistently and you can't tell if it's the model or the config — that's exactly what the Agent Audit covers. Review of all five core files, specific recommendations, 48-hour turnaround. → Agent Audit details

---