Troubleshooting
Heartbeat Keeps Repeating Old Tasks?
Fix repetitive heartbeat behavior so your agent stops re-running stale work and only acts on current priorities.
A common complaint is: "My agent keeps doing the same heartbeat tasks over and over." This usually happens when heartbeat instructions are too vague, too long, or still include old one-time tasks.
Core idea: heartbeat should be a short, living checklist. Not a permanent to-do dump.
Why this happens
- Stale instructions: completed tasks were never removed from
HEARTBEAT.md.
- No "do not repeat" rule: the agent has no explicit stop condition.
- No state tracking: checks run every poll because last-run timestamps are missing.
- Mixed priorities: urgent one-offs and recurring checks are blended together.
Quick fix (5 minutes)
1) Keep HEARTBEAT.md short
Limit it to current recurring checks and high-priority active reminders. Archive old items elsewhere.
2) Add explicit non-repetition instructions
Tell the agent to avoid repeating completed work unless there is new input.
3) Separate recurring checks from one-time tasks
Put one-time actions in a dated checklist and remove them once done.
4) Track state in a small JSON file
Store timestamps like lastChecks.email, lastChecks.calendar, and only re-check when enough time has passed.
Copy/paste heartbeat policy block
# Heartbeat Rules
- Read this file each heartbeat.
- Do NOT infer or repeat old tasks from previous chats.
- Only run recurring checks listed below.
- For one-time tasks: execute once, then remove or mark done.
- If nothing new needs attention, reply exactly: HEARTBEAT_OK
## Recurring checks
- Email: max every 3 hours
- Calendar (next 24h): max every 2 hours
- Mentions/alerts: max every 2 hours
## State
- Use memory/heartbeat-state.json to track last check timestamps.
Important: if your heartbeat prompt says "follow HEARTBEAT.md strictly," any stale line in that file is likely to be re-executed. Keep it clean.
Known-good heartbeat-state.json example
{
"lastChecks": {
"email": 1774956000,
"calendar": 1774959600,
"mentions": 1774959600
},
"lastSummaryAt": 1774961400
}
How to verify the fix worked
- Trigger two heartbeat cycles within ~15 minutes.
- First run performs checks and updates timestamps.
- Second run should skip repeated checks and return
HEARTBEAT_OK unless something changed.
Bottom line: heartbeat quality is mostly instruction hygiene. Short checklist, explicit stop rules, and state tracking = calm, useful, non-spammy behavior.