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.
“HEARTBEAT prompt showed up in chat” → normal occasionally; reply exactly HEARTBEAT_OK once, then continue.
“I typed HEATBEAT_OK and nothing happened” → typo; use HEARTBEAT_OK (with the R).
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.
Heartbeat reads but does not execute your tiny task → likely capability mismatch, approval-gated commands, or instruction conflict. See advanced checks below.
Using heartbeat as cron replacement for exact-time jobs → heartbeat is periodic and can drift; use cron for exact schedule requirements.

Advanced checks for “heartbeat runs, but nothing actually happens”

This is a recurring trust-break: the heartbeat appears to run, but your requested action (like posting a daily econ reminder) never lands.

1) Separate “must run at exact time” from “periodic checks”

Use heartbeat for loose periodic checks. Use cron for exact schedules (for example, weekdays at 8:30 AM). If exact timing matters, heartbeat alone is the wrong tool.

2) Test with a tiny no-tool canary

Temporarily replace your checklist with one line: "On heartbeat, reply with: HEARTBEAT_CANARY_OK + current local time." If this fails, your issue is heartbeat routing/config, not your task logic.

3) Check for approval-gated or unavailable actions

If your heartbeat asks for actions that require unavailable tools or approval, the run may look “stuck.” Start by verifying a plain text output works first, then add one external action at a time.

4) Remove conflicting instruction layers

Conflicts across SOUL.md, AGENTS.md, and HEARTBEAT.md can cancel execution. Add a clear heartbeat override line such as: "During heartbeat runs, follow HEARTBEAT.md checklist first."

Reality check: heartbeat is best for batching low-urgency checks. For strict delivery windows (market open, econ calendar, meeting reminders), pair heartbeat with cron instead of forcing heartbeat to act like a scheduler.

If the heartbeat prompt appears mid-conversation

Users often panic when they suddenly see a heartbeat line in chat. In most cases this is expected system behavior, not agent failure.

1) Reply with the exact no-op phrase

Send HEARTBEAT_OK exactly once (all caps, include the R).

2) Continue your normal task

You do not need to restart your agent or rewrite your prompts just because a heartbeat surfaced in chat.

3) Only escalate if it appears repeatedly every few minutes

If heartbeat prompts flood chat, share timestamps and your current HEARTBEAT.md in #help so support can verify scheduling/config drift.

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.