Troubleshooting

HEARTBEAT.md Errors?

Fix the most common heartbeat file mistakes in minutes so your agent stops repeating errors and starts doing useful check-ins.

If your agent keeps saying there is a HEARTBEAT.md error, you are not alone. This is a common setup issue and usually comes down to file location, formatting, or stale instructions.

Good news: you usually do not need to reinstall anything. A small file fix solves this most of the time.

What HEARTBEAT.md is for

A short checklist for periodic heartbeat runs
What the agent should check (email, calendar, mentions, etc.)
When to notify you vs stay quiet
How to avoid repeating old tasks forever

Quick fix checklist (in order)

1) Confirm the file path is exactly right

The file should be in your workspace root, named exactly HEARTBEAT.md (all caps, no extra extension).

✅ HEARTBEAT.md ❌ heartbeat.md ❌ HEARTBEAT.md.txt ❌ /memory/HEARTBEAT.md

2) Keep it short and explicit

Overly long heartbeat instructions can create confusion and repeated loops. Keep it to a tight checklist.

3) Remove stale “always do X” language

If your file says to always run old tasks, the agent may keep doing them forever. Use conditional rules instead.

4) Add a clear no-op rule

Tell the agent what to do when nothing needs attention (for example: return HEARTBEAT_OK).

5) Run one heartbeat test

After edits, trigger one heartbeat and confirm behavior before adding more complexity.

Known-good HEARTBEAT.md starter

# HEARTBEAT.md Check only these items: 1) Calendar events in next 24h 2) Urgent unread email 3) New direct mentions Rules: - If nothing important changed since last check, reply HEARTBEAT_OK. - Do not repeat the same suggestion twice in a row. - Keep responses to 3 bullets max unless urgent. - Quiet hours: 11pm-8am local time unless urgent.

Tip: if your heartbeat keeps revisiting old tasks, also track simple state in a small JSON file (last check timestamps). That prevents repetitive behavior.

Common error patterns and fixes

“File not found” → HEARTBEAT.md is in the wrong folder or wrong filename case.
Repeats the same message every run → missing “do not repeat” rule and no state tracking.
Runs too many checks every heartbeat → checklist is too broad; trim to 3-5 items max.
Noisy messages at night → add explicit quiet hours with an urgency exception.

Avoid this anti-pattern: “Check everything all the time and summarize everything.” That instruction guarantees noisy, expensive, low-signal output.

When to ask for help

If the issue continues after this checklist, include these details in #help:

Your current HEARTBEAT.md content
The exact error text
One example of unexpected heartbeat output
What changed right before the issue started

Bottom line: a clean, short HEARTBEAT.md gives calm, useful check-ins. Keep it simple, conditional, and test once after every edit.