Heartbeat

The heartbeat system lets BabyClaw run periodic agent check-ins on a schedule. Instead of only responding when you message it, the agent can proactively check things and alert you if something needs attention.

Heartbeat is disabled by default. Enable it when you want the agent to do background work.

Enabling heartbeat

{
  "heartbeat": {
    "enabled": true,
    "intervalMinutes": 30
  }
}

This runs a heartbeat every 30 minutes. The minimum interval is 5 minutes.

How it works

On each heartbeat:

1. The agent reads HEARTBEAT.md from the workspace (if it exists)
2. It follows the instructions in that file
3. It decides whether anything needs attention
4. If something does, it sends you a message. If not, it stays quiet.

The key idea: silent when nothing's happening, vocal when something matters.

Writing a HEARTBEAT.md

The HEARTBEAT.md file in your workspace tells the agent what to check during heartbeats. Keep it short -- each heartbeat costs tokens.

Example:

# Heartbeat Checklist

- Check if there are any unread emails from $BOSS
- Look at my calendar for the next 4 hours -- anything coming up?
- If the weather is going to be bad today, let me know

The agent will work through these items and only message you if something stands out. If everything looks fine, it stays quiet.

You can also let the agent edit this file over time -- it might add items based on your conversations.

Active hours

If you don't want heartbeats at 3am, set an active window:

{
  "heartbeat": {
    "enabled": true,
    "intervalMinutes": 30,
    "activeHours": {
      "start": "08:00",
      "end": "22:00"
    }
  }
}

Times are in 24-hour format and use the scheduler.timezone from your config. Outside this window, heartbeats are skipped.

Custom prompt

You can change the prompt sent to the agent on each heartbeat:

{
  "heartbeat": {
    "prompt": "Check HEARTBEAT.md. If nothing needs attention, stay quiet."
  }
}

The default prompt is:

"Read HEARTBEAT.md if it exists. Follow its instructions. Do not infer or repeat old tasks from prior chats. If nothing needs attention, say so."

Heartbeat vs scheduling

Both heartbeat and scheduling can trigger the agent periodically, but they work differently:

A common pattern: use heartbeat for background monitoring (email, calendar, weather) and scheduling for specific tasks ("remind me in 20 minutes", "every Monday at 9am").

Checking heartbeat status

In Telegram, use the /heartbeat command to see if heartbeat is enabled and when the next run is scheduled.