HEARTBEAT.md Explained: How to Make Your Agent Proactive

HEARTBEAT.md is where an agent learns to check things on a schedule instead of waiting to be asked. It is the difference between a reactive assistant and one that quietly keeps an eye on the things you care about. Set up well, the agent stops feeling like a bot you prompt and starts feeling like a process watching the important edges of your workflow.

This guide explains what a heartbeat actually does, what HEARTBEAT.md should control, and the rules that keep proactive agents useful instead of noisy.

What heartbeat checks are

A heartbeat is a periodic pass. The agent wakes on a tick, reads the rules in HEARTBEAT.md, checks its state file, and decides whether anything noteworthy happened. If nothing important changed, it stays quiet. That quiet part is the feature: a useful heartbeat does not create noise for the sake of activity, because noise is what makes people disable proactive agents.

Mechanically, the heartbeat runs on an interval with an active-hours window, so it ticks during the day and sleeps at night. On each tick the agent has full session context, which is what lets it make judgment calls about whether an email is urgent or a release is worth covering.

What HEARTBEAT.md should control

The file should describe what to check, how often to check it, when to alert, and when to ignore the result. It should also say what the agent should do when it finds something interesting: draft a post, summarize a result, log a note. The best heartbeat rules are narrow. The more focused the check, the less token waste and the less false alarm fatigue, because a rule that says “watch for updates” produces noise while a rule that names the update worth sharing produces posts.

Anatomy of one check

A good heartbeat rule is a full decision path, not a vague instruction. The news-monitor style check that powers the updates on this site is the model:

anatomy of one check
# A heartbeat rule is a full decision path, not a vibe

trigger     check OpenClaw news every few days
process     fetch updates, compare with the last seen state
noteworthy  a real release or breaking change
ignore      version bumps, minor fixes, marketing posts
action      if noteworthy: draft a post and flag it

# Narrow rules: less token waste, less alarm fatigue.
# Vague instructions to watch for updates produce noise.

Every part of that rule exists to remove guessing. The trigger says when the pass runs. The process says what the agent actually does. The noteworthy line is the threshold that separates an alert from silence, and the ignore list is the other half of that threshold. The action closes the loop so the agent knows what to do with what it found.

What belongs on the heartbeat versus in cron is a decision worth making once. The heartbeat is for judgment passes that benefit from session context: reading a mailbox and deciding what is urgent, checking the calendar for conflicts, folding memory. Cron is for exact schedules and deterministic output: a fixed-time report, a scripted probe, a one-shot reminder. The general rule: if the check needs reasoning about what it finds, heartbeat; if it needs precision about when it runs, cron.

Why state tracking matters

Without state, a heartbeat cannot tell new from old, so it re-checks everything every pass and repeats the same work over and over. A small state file next to the rules fixes that:

state file: stop repeating work
# Track what was checked and when, next to the rules
{
  "lastChecks": {
    "email": 1725400000,
    "news": 1725486400,
    "calendar": 1725400000
  }
}

# The agent reads state before each pass, so it only
# checks what is due, not everything every time.

# Batching: group related checks, respect quiet hours,
# and stay silent when nothing changed.

Reading state before each pass lets the agent check only what is due, which keeps the pass cheap and the results meaningful. The state file is also how the agent knows what it already saw, so it does not alert twice about the same release or the same inbox item.

Batching and quiet hours

One of the easiest mistakes is checking everything on every heartbeat. That burns tokens and creates noise. The better pattern is to group related checks into batches and spread them across the day, with quiet hours in the rules so nothing fires when the human is asleep. When the agent knows what was checked and when, it can cover more ground without spinning its wheels.

The full loop looks like this:

The off switch

Every proactive setup needs a pause button, and HEARTBEAT.md has a built-in one. The file this site’s agent actually runs is comments-only right now, and that is a deliberate state:

user@host:~$ cat HEARTBEAT.md

<!-- Heartbeat template; comments-only content prevents scheduled
heartbeat API calls. -->

# Keep this file empty (or with only comments) to skip heartbeat
# API calls.
# Add tasks below when you want the agent to check something
# periodically.

# Comments only: the tick still runs, but nothing fires.

Comments-only content means the heartbeat ticks but makes no API calls. The configuration survives, the checks stay written down, and the moment you want the agent watching again, you uncomment the rules and the system resumes. That is the correct way to pause proactive behavior: without deleting the design.

What changes when you expand it

Add email to HEARTBEAT.md and the agent can summarize the inbox twice a day without being asked. Add calendar checks and it flags conflicts before they bite. Add site health and it catches outages at the first failed probe. That power cuts both ways: the same file can create a lot of value or a lot of noise, and the difference is entirely in how specific the rules are. Expand one check at a time, watch the alert rate, and keep the bar for noteworthy high enough that silence is the norm.

A final calibration tip: when you first enable a heartbeat, expect a few noisy days while the noteworthy bar is too low, then tighten the rules until alerts are rare and always relevant. The goal is not more activity; it is the right activity, at the right time, with silence as the default.

Quick tips

• Check only what matters; narrow rules beat ambitious ones.
• Track the last run time in a state file so nothing repeats.
• Define what counts as noteworthy and what to ignore.
• Keep quiet hours in the rules.
• Batch related checks together instead of checking everything each tick.

HEARTBEAT.md is how OpenClaw stops waiting around and starts paying attention on its own. The deeper patterns live across this site’s heartbeat cluster: templates and examples, auditing a heartbeat setup, and the state file explained. If heartbeats never fire, the troubleshooting guide covers the config checks, and the ten-check rotation in what your agent should check automatically is the natural companion. The workspace-file series lives under The Complete OpenClaw Guide.

This post contains affiliate links. If you buy through them, I may earn a small commission at no extra cost to you.

About The Author

Marcus Li

Marcus Li is a web designer and marketing specialist based in Vancouver, BC. After years of helping clients build their online presence, he discovered how AI tools could level the playing field for everyday entrepreneurs. He shares what actually works, no fluff, no hype.

See author's posts