vellum-heartbeat

---
name: vellum-heartbeat
description: Configure periodic background checklist runs
compatibility: "Designed for Vellum personal assistants"
metadata:
  emoji: "💓"
  vellum:
    category: "system"
    display-name: "Heartbeat"
    activation-hints:
      - "Set up a heartbeat, periodic checklist, background health check, or recurring background task"
    avoid-when:
      - "One-off or recurring schedules with specific payloads - use the schedule skill instead"
---

The heartbeat feature runs your `HEARTBEAT.md` checklist periodically in a background conversation. Each run, the assistant works through the checklist and flags anything that needs attention.

## Setup

Edit `config.json` using `file_edit`:

1. **Enable heartbeat**: Set `heartbeat.enabled` to `true`.
2. **Set interval**: Set `heartbeat.intervalMs` (milliseconds between runs, default: 3600000 = 1 hour).
3. **Optional active hours**: Set `heartbeat.activeHoursStart` and `heartbeat.activeHoursEnd` (0-23) to restrict runs to certain hours in the heartbeat timezone. Hours use `heartbeat.timezone` when set, otherwise the user's configured or detected timezone (the host clock is last resort). Both must be set together.

Example config.json heartbeat section:

```json
{
  "heartbeat": {
    "enabled": true,
    "intervalMs": 1800000,
    "activeHoursStart": 8,
    "activeHoursEnd": 22
  }
}
```

Then edit `HEARTBEAT.md` with the checklist items. The assistant will work through this file each heartbeat run.

## Notes

- Toggling `heartbeat.enabled` requires an assistant restart to take effect.
- Changes to `HEARTBEAT.md` take effect on the next heartbeat run (no restart needed).
- The heartbeat runs in a separate background conversation, not the user's active chat.

## Inference

Heartbeat runs use the `heartbeatAgent` call site, which by default resolves to the
`cost-optimized` profile so background checks stay cheap. Override via
`llm.callSites.heartbeatAgent` in workspace config (profile, provider, model,
effort, thinking — whatever the profile supports).