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:

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