Skip to main content

​
Proactive Heartbeat

Your UltraClaw agent doesn’t just wait for you to ask questions — it can proactively monitor things and reach out when something needs your attention. This is the heartbeat system.

​
How It Works

At a configurable interval, your agent wakes up, reads your HEARTBEAT.md instructions, and executes the checks you’ve defined. If something needs your attention, it sends you a message. If everything is fine, it stays silent.
1

Agent Wakes Up

At each heartbeat interval, your agent activates in an isolated session.
2

Reads HEARTBEAT.md

Your agent reads the instructions in your HEARTBEAT.md workspace file — these define exactly what to check.
3

Runs Checks

Your agent performs the defined checks using its integrations and skills (check email, look up weather, query a service, etc.).
4

Notifies Only When Needed

If something requires your attention, your agent sends you a message. If everything checks out, it returns HEARTBEAT_OK and stays silent.
HEARTBEAT_OK means silence. Your agent only reaches out when there’s something actionable. No “all clear” spam — just signal, never noise.

​
Configuring Heartbeat

​
Setting the Interval

Configure how often your agent checks in from your dashboard under Settings > Heartbeat. Common intervals:
IntervalGood For
Every 15 minutesTime-sensitive monitoring (inbox, alerts)
Every 30 minutesActive workday monitoring
Every hourGeneral-purpose checks
Every 4 hoursLow-frequency oversight

​
Active Hours

Set active hours so your agent only runs heartbeat checks during times you want to be notified. For example:
  • Workday only: 8am – 6pm, Monday through Friday
  • Waking hours: 7am – 11pm, every day
  • Always on: 24/7 monitoring
Without active hours configured, heartbeat checks run around the clock. Set active hours to avoid middle-of-the-night notifications.

​
Writing HEARTBEAT.md

Your HEARTBEAT.md file tells your agent exactly what to check. Be specific and actionable: 
## Heartbeat Instructions

1. Check my Gmail inbox for any emails flagged as urgent
   or from anyone in my VIP contacts list.
   Notify me with the sender, subject, and a one-line summary.

2. Check the weather forecast for San Francisco.
   Only notify me if rain is expected in the next 6 hours.

3. Check my Google Calendar for any meetings in the next 2 hours
   that I haven't confirmed yet.
Write your HEARTBEAT.md instructions like you’re delegating to a human assistant. Be clear about what to check, when to notify, and what to include in the notification.

​
Use Cases

Inbox Monitoring

Get notified about urgent emails, messages from VIP contacts, or emails matching specific keywords — without checking your inbox constantly.

Weather Alerts

Your agent checks the forecast and texts you only when conditions matter — rain before your outdoor event, freezing temps overnight, etc.

Price Tracking

Monitor prices on products or services. Your agent checks periodically and notifies you when a price drops below your threshold.

Calendar Prep

Get proactive reminders about upcoming meetings, including context from previous conversations with attendees.

Server & Service Monitoring

Have your agent check the status of websites, APIs, or services and alert you if something goes down.

News & Research

Monitor news sources or topics relevant to your work. Get notified only when something significant happens.

​
Heartbeat vs. Cron Jobs

Both features let your agent do things on a schedule, but they serve different purposes:
HeartbeatCron Jobs
PurposeMonitor and alertExecute tasks
OutputNotification only if actionableAlways produces output
ConfigurationHEARTBEAT.md fileCron schedule + payload
Behavior when nothing to reportSilent (HEARTBEAT_OK)Still runs the task
Use heartbeat for monitoring and alerting. Use cron jobs for scheduled tasks like morning briefings or weekly reports.