What HEARTBEAT.md is for
If you want an AI agent to be useful without being micromanaged, you need to tell it what to watch. That is what HEARTBEAT.md does. It is a simple instruction file that turns a passive assistant into a proactive one. Instead of waiting for prompts, the agent checks important things on a schedule and acts when something needs attention.
In OpenClaw, that might mean checking email, calendar events, weather, inbox triage, project notes, or system health. The idea is simple: give the agent a short list of recurring responsibilities, then let it keep an eye on the world for you.
Where to put it
Place HEARTBEAT.md in the root of your workspace or wherever your agent reads session instructions from. Keep it easy to find. The file should be plain, readable, and written like a working checklist, not a policy manual.
What to include
Good heartbeat files usually have four parts:
- What to check so the agent knows the target.
- How often to check so the routine is clear.
- What counts as urgent so it can escalate correctly.
- What to do next so the response is useful, not just observant.
Start small
Do not start with twenty checks. Start with three to five things that matter every day. That could be email, calendar, weather, and memory review. Once that works, expand slowly. A small heartbeat file that runs reliably is far better than a giant one nobody maintains.
Real checks to add
Here are practical examples that actually help:
- Email: flag urgent messages, deadlines, or client replies.
- Calendar: surface events coming up in the next 24 to 48 hours.
- Weather: useful if the user may commute, travel, or leave the house.
- Memory: review recent notes and carry forward anything important.
- Project status: check whether active work is stalled or ready for the next step.
Sample HEARTBEAT.md template
# HEARTBEAT.md
## Purpose
Keep the agent proactive by checking important signals on a regular basis.
## Daily checks
- Email inbox for urgent or time-sensitive messages
- Calendar for events within the next 48 hours
- Weather if travel or errands are likely
- Memory notes for decisions that should be carried forward
## Weekly checks
- Review project progress and stalled tasks
- Check website or SEO health if relevant
- Scan for anything that has changed in priorities
## Escalate when
- A message is urgent or blocked
- A deadline is within 24 hours
- An event is at risk of being missed
- A project needs a human decision
## When to stay quiet
- Nothing changed since the last check
- The issue is informational, not urgent
- It is outside the user's active hoursHow to make it actually work
The best heartbeat files are specific. They tell the agent what matters, what is noise, and how to respond when something is off. Avoid vague lines like ‘check important things.’ That is too broad to be useful. Say exactly what counts as important.
Also, remember to revise the file. If a check stops being useful, remove it. If something new becomes critical, add it. HEARTBEAT.md should evolve with the way you work.
Bottom line
If you want your agent to feel less like a chatbot and more like a teammate, give it a heartbeat. Keep the file short, concrete, and action-oriented. That small bit of structure is what turns passive automation into real proactive help.
Not Ready to Self-Host? Try ClawTrust
Building agents locally is powerful, but managing infrastructure, security, and scaling takes effort. ClawTrust provides managed OpenClaw hosting — your agents run securely in the cloud with automatic scaling, no DevOps overhead, and 24/7 monitoring.
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
the HEARTBEAT.md concept is really clever. treating agent awareness as a config file is so much cleaner than hardcoding check intervals. gonna refactor mine today
Thanks for reading, Owen Hughes. On Write HEARTBEAT md Scratch Make, I would start with the basics and then tighten things up once you see how it behaves in practice. If you are already testing it, the main thing is to keep the setup simple enough to debug quickly.
I’ve had my heartbeat set up for a month but it wasn’t doing half of what you describe here. Time to rewrite it.
Thanks for reading, Sam Kowalski. For Write HEARTBEAT md Scratch Make, I would start with the simplest workable setup and only add complexity if you actually need it. That keeps things easier to troubleshoot and usually gets you to a better result faster.
I love that this makes the agent actually proactive instead of just reactive. Big difference in day-to-day usefulness.
How often should you update your HEARTBEAT.md as your needs change?
I review mine every 2-3 weeks. Treat it like a living document , add what works, remove what doesn’t.
Glad it helped. On Write HEARTBEAT md Scratch Make, the big win is usually getting the first pass right and then refining from there. That tends to save a lot of time later.
This clicked something for me. I had the file set up but didn’t really understand the purpose until now.
Glad it helped. On Write HEARTBEAT md Scratch Make, the big win is usually getting the first pass right and then refining from there. That tends to save a lot of time later.
Can you share a template version of your HEARTBEAT.md? Even a basic one would be helpful.
Yes! Putting together a starter HEARTBEAT.md template , will share it in the next post.
Setting this up this weekend. Appreciate how specific the examples are.
Great question. For Write HEARTBEAT md Scratch Make, I would start with the simplest workable setup and only add complexity if you actually need it. That keeps things easier to troubleshoot and usually gets you to a better result faster.
The quiet hours logic is something I never thought to add. My agent was pinging me at 3am. Fixed now.
Thanks for reading, Jordan Blake. On Write HEARTBEAT md Scratch Make, I would start with the basics and then tighten things up once you see how it behaves in practice. If you are already testing it, the main thing is to keep the setup simple enough to debug quickly.
The part about batching checks instead of running them individually is a great tip. Hadn’t thought about token efficiency.
Glad it helped. On Write HEARTBEAT md Scratch Make, the big win is usually getting the first pass right and then refining from there. That tends to save a lot of time later.
This is the most practical guide to HEARTBEAT.md I’ve found. Most explanations are too abstract.
Thanks for reading, David Park. On Write HEARTBEAT md Scratch Make, I would start with the basics and then tighten things up once you see how it behaves in practice. If you are already testing it, the main thing is to keep the setup simple enough to debug quickly.
glad someone wrote a proper guide for this. the docs are a little sparse on heartbeat setup and this fills the gaps nicely
Thanks for reading, Lin Cho. On Write HEARTBEAT md Scratch Make, I would start with the basics and then tighten things up once you see how it behaves in practice. If you are already testing it, the main thing is to keep the setup simple enough to debug quickly.
The ‘what to check vs when to bother you’ framing is exactly what I needed. My agent was interrupting me constantly until I got clear on this distinction.
Thanks for reading, Erin C.. For Write HEARTBEAT md Scratch Make, I would start with the simplest workable setup and only add complexity if you actually need it. That keeps things easier to troubleshoot and usually gets you to a better result faster.
Took me about 20 minutes to rewrite my HEARTBEAT.md using this as a guide and the agent behavior immediately improved. Fewer unnecessary pings and it actually catches the stuff that matters.
Thanks for reading, Simon B.. On Write HEARTBEAT md Scratch Make, I would start with the basics and then tighten things up once you see how it behaves in practice. If you are already testing it, the main thing is to keep the setup simple enough to debug quickly.