Skip to main content
Heartbeats are background turns that let Moldable check for attention-needed work on a cadence without spamming channels.

​
Core Behavior

  • Heartbeats run on gateway ticks when gateway.heartbeat.enabled is true.
  • Each target uses heartbeat.every to decide due time (0 disables the target).
  • Heartbeats read HEARTBEAT.md instructions and should return HEARTBEAT_OK when clear.
  • Runtime preflight resolves canonical file paths before model execution:
    • global: HEARTBEAT.md
    • team: teams/<team>/HEARTBEAT.md and teams/<team>/TEAM.md
  • Runs skip before model execution when required files are missing, unreadable, or effectively empty.
  • HEARTBEAT_OK-only replies are suppressed by default for low-noise behavior.
  • Repeated identical alert payloads are suppressed for 24 hours.
  • 5m - very high-sensitivity operations triage
  • 15m - active project monitoring
  • 30m - balanced default (recommended)
  • 1h - normal background monitoring
  • 4h or 8h - low-noise daily operations checks
  • 24h - daily hygiene checks
Use team heartbeats for work that should stay scoped to one team.
  1. Enable team heartbeat in Team Settings.
  2. Keep cadence at 30m unless there is a clear need to increase.
  3. Edit teams/<team>/HEARTBEAT.md with an explicit checklist.
  4. Keep default mode read-only unless explicit mutating steps are intentionally documented.
Example HEARTBEAT.md: 
# Team heartbeat checklist

- Review inbox for urgent follow-ups.
- Check in-progress tasks for blockers or stale ownership.
- If blocked, report what is missing and who is needed.
- If no action is required, reply HEARTBEAT_OK.

​
Visibility Controls

Heartbeat visibility is controlled by:
  • channel defaults: channels.defaults.heartbeat
  • per-channel overrides: channels.<channel>.heartbeat
Flags:
  • showOk - send HEARTBEAT_OK messages
  • showAlerts - send actionable alerts
  • useIndicator - emit visual/log status indicators

​
Active Hours

Use heartbeat.activeHours to constrain delivery windows:
  • start: "09:00"
  • end: "18:00"
  • timezone: "user", "local", or IANA timezone like "America/New_York"
If active-hours config is invalid, heartbeat falls back to permissive behavior instead of failing closed.