# Vellum Heartbeat

> Configure periodic background checklist runs

- Skill: `vellum-ai/vellum-heartbeat` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vellum-ai/vellum-heartbeat`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vellum-ai/vellum-heartbeat/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: vellum-ai (https://skillmd.com/u/vellum-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vellum-ai/vellum-heartbeat

---


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