> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ultraclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Proactive Heartbeat

> Your UltraClaw AI agent can proactively check in and notify you when something needs attention.

# 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.

<Steps>
  <Step title="Agent Wakes Up">
    At each heartbeat interval, your agent activates in an isolated session.
  </Step>

  <Step title="Reads HEARTBEAT.md">
    Your agent reads the instructions in your HEARTBEAT.md workspace file — these define exactly what to check.
  </Step>

  <Step title="Runs Checks">
    Your agent performs the defined checks using its integrations and skills (check email, look up weather, query a service, etc.).
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Info>
  **HEARTBEAT\_OK means silence.** Your agent only reaches out when there's something actionable. No "all clear" spam — just signal, never noise.
</Info>

## Configuring Heartbeat

### Setting the Interval

Configure how often your agent checks in from your [dashboard](https://ultraclaw.ai/dashboard) under **Settings > Heartbeat**. Common intervals:

| Interval         | Good For                                  |
| ---------------- | ----------------------------------------- |
| Every 15 minutes | Time-sensitive monitoring (inbox, alerts) |
| Every 30 minutes | Active workday monitoring                 |
| Every hour       | General-purpose checks                    |
| Every 4 hours    | Low-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

<Warning>
  Without active hours configured, heartbeat checks run around the clock. Set active hours to avoid middle-of-the-night notifications.
</Warning>

### Writing HEARTBEAT.md

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

```markdown theme={null}
## 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.
```

<Tip>
  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.
</Tip>

## Use Cases

<CardGroup cols={2}>
  <Card title="Inbox Monitoring" icon="envelope">
    Get notified about urgent emails, messages from VIP contacts, or emails matching specific keywords — without checking your inbox constantly.
  </Card>

  <Card title="Weather Alerts" icon="cloud-rain">
    Your agent checks the forecast and texts you only when conditions matter — rain before your outdoor event, freezing temps overnight, etc.
  </Card>

  <Card title="Price Tracking" icon="tag">
    Monitor prices on products or services. Your agent checks periodically and notifies you when a price drops below your threshold.
  </Card>

  <Card title="Calendar Prep" icon="calendar">
    Get proactive reminders about upcoming meetings, including context from previous conversations with attendees.
  </Card>

  <Card title="Server & Service Monitoring" icon="server">
    Have your agent check the status of websites, APIs, or services and alert you if something goes down.
  </Card>

  <Card title="News & Research" icon="newspaper">
    Monitor news sources or topics relevant to your work. Get notified only when something significant happens.
  </Card>
</CardGroup>

## Heartbeat vs. Cron Jobs

Both features let your agent do things on a schedule, but they serve different purposes:

|                                     | Heartbeat                       | Cron Jobs               |
| ----------------------------------- | ------------------------------- | ----------------------- |
| **Purpose**                         | Monitor and alert               | Execute tasks           |
| **Output**                          | Notification only if actionable | Always produces output  |
| **Configuration**                   | HEARTBEAT.md file               | Cron schedule + payload |
| **Behavior when nothing to report** | Silent (HEARTBEAT\_OK)          | Still runs the task     |

Use **heartbeat** for monitoring and alerting. Use **[cron jobs](/assistant/cron-jobs)** for scheduled tasks like morning briefings or weekly reports.