> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironclaw.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Heartbeat System
> Periodic checks and execution
The heartbeat system gives IronClaw agency between conversations. Every 30 minutes (by default), it reads `HEARTBEAT.md` from the workspace and executes a checklist of proactive tasks — without you having to ask.
You can setup how often the agent checks the heartbeat list
***
## What Heartbeat Does
On each heartbeat tick:
1. Reads `HEARTBEAT.md` from the workspace root
2. Runs the checklist items as an agent job
3. If the job produces findings or output, sends a notification to the configured channel
4. Records the run in the `heartbeat_state` table
If `HEARTBEAT.md` does not exist or is empty, the tick is a no-op.
The heartbeat job runs through the full agent loop — LLM reasoning, tool calls, safety layer — with the same capabilities as a manually triggered job.
***
## HEARTBEAT.md Format
Write `HEARTBEAT.md` as a checklist of tasks. The agent reads this as its instructions for each periodic run:
```markdown theme={null}
# Heartbeat Checklist
## Daily Tasks
- [ ] Check memory at daily/ for yesterday's notes. If missing, remind the user.
- [ ] Search memory for any items tagged as "follow-up" or "urgent" and list them.
- [ ] Read ops/stuck-jobs.md if it exists and summarize any unresolved incidents.
## Weekly Tasks (run only on Mondays)
- [ ] Summarize the week's daily notes into a weekly summary at weekly/.md
- [ ] Check for any routines that haven't run in the past 7 days and flag them.
## Always
- [ ] If any of the above produce findings, write a summary to memory at heartbeat/latest.md
- [ ] Only notify the user if there are actionable items — do not send empty pings.
```
The agent interprets the checklist and executes each item using available tools. Conditional items ("run only on Mondays") are evaluated by the LLM using the current date.
***
## Notification Behavior
After each tick, if the job produces output that warrants user attention, the heartbeat system sends a notification to the configured channel. If nothing actionable was found, no notification is sent — heartbeat is designed to be quiet unless it has something useful to say.
Findings are also written to memory at `heartbeat/latest.md` (if your HEARTBEAT.md instructs this), making them searchable in future sessions.
***
## Configuration
```bash theme={null}
# Enable heartbeat (default: true)
HEARTBEAT_ENABLED=true
# Interval between ticks in seconds (default: 1800 = 30 minutes)
HEARTBEAT_INTERVAL_SECS=1800
# Channel to send notifications to
HEARTBEAT_NOTIFY_CHANNEL=tui # tui, web, telegram, webhook
# User ID to notify
HEARTBEAT_NOTIFY_USER=default
```
Set `HEARTBEAT_INTERVAL_SECS=3600` (1 hour) or higher if the heartbeat job is too frequent for your LLM API rate limits or budget. The heartbeat runs as a normal job and consumes tokens.
***
## Writing HEARTBEAT.md
Ask the agent to create or update the heartbeat checklist:
```
Write HEARTBEAT.md with tasks to check my inbox/ folder every 30 minutes
and summarize any new items.
```
Or edit the file manually:
```
memory_write path="HEARTBEAT.md" content="
# Heartbeat Checklist
- [ ] List all memory documents in inbox/ — if any exist, summarize and move to processed/
- [ ] Check if daily/.md exists — if not, create a daily entry template
- [ ] Only notify if inbox/ had items or daily notes were missing
"
```
***
## Example HEARTBEAT.md Files
### Minimal — Inbox Monitor
```markdown theme={null}
# Heartbeat
- [ ] Check inbox/ for new documents. Process and move to processed/. Notify only if items were found.
```
***
### Developer Workflow
```markdown theme={null}
# Heartbeat Checklist
## Checks
- [ ] Read ops/incidents/ — summarize any open incidents older than 24 hours
- [ ] Check for stuck jobs in the last hour
- [ ] Look for daily/.md — create it with a timestamp if missing
## Output
- [ ] Write findings to heartbeat/latest.md
- [ ] Notify only if there are open incidents or stuck jobs
```
***
### Personal Assistant
```markdown theme={null}
# Heartbeat
- [ ] Search memory for items tagged "reminder" or "todo"
- [ ] Check if any items are due today based on their content
- [ ] Summarize time-sensitive items and notify
- [ ] Do not notify if nothing is due
```
***
## Heartbeat vs Routines
Heartbeat and cron routines serve similar purposes but differ in design:
| Feature | Heartbeat | Cron Routine |
| ------------- | ------------------------ | ----------------------------------- |
| Configuration | Single HEARTBEAT.md file | Per-routine configuration |
| Schedule | Fixed global interval | Custom per-routine cron expression |
| Scope | Single checklist job | Multiple independent jobs |
| Complexity | Simple — edit one file | Flexible — manage multiple routines |
Use heartbeat for a unified set of periodic checks. Use cron routines when you need different schedules for different tasks, or when tasks should run independently.
***
## Troubleshooting
* Verify `HEARTBEAT_ENABLED=true` in your configuration
* Check startup logs for `heartbeat` to confirm the system started
* Confirm `HEARTBEAT_INTERVAL_SECS` is set to a reasonable value
* Verify `HEARTBEAT.md` exists in the workspace root via `memory_read path="HEARTBEAT.md"`
* Update HEARTBEAT.md to add a condition: "only notify if there are actionable items"
* Increase `HEARTBEAT_INTERVAL_SECS` to reduce frequency
* Make checklist items more specific so the agent doesn't over-report
* Simplify HEARTBEAT.md — fewer checklist items mean fewer LLM calls
* Increase `HEARTBEAT_INTERVAL_SECS` to reduce frequency
* Add guardrails-style instructions to HEARTBEAT.md: "Use at most 5 tool calls per run"