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

# Heartbeats

> Low-noise periodic checks for agents and teams.

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.

## Recommended Cadence Defaults

* `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

## Team Pattern (Recommended)

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`:

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