Heartbeat#
The heartbeat is a Lens Prism agent's always-on monitoring loop. On a schedule, the agent wakes up, runs the checks you've configured, and decides on its own whether anything is worth telling you about. It's what makes the agent proactive rather than purely reactive.
On each tick the agent runs the checks defined in its Heartbeat document (see Agent identity) using its full toolset, passes the result through a fast DELIVER/SUPPRESS classification gate, and delivers an alert only if the gate says DELIVER. You configure what it checks by editing the Heartbeat document — tell the agent what to watch. You configure how often with the interval.
The check runs on the agent's main model by default. Give the heartbeat its own model to run routine checks on a cheaper model: set it from the web UI Profile page or the terminal UI (/heartbeat-model <ID>), and leave it empty to use the main model. The DELIVER/SUPPRESS gate always runs on its own fast model regardless.
Cadence#
The default interval is every 8 hours, configurable per agent with a minimum of 1 minute. Set it from the web UI Profile page (an inline editor, 1–10080 minutes), from the terminal UI with /heartbeat every 2h, or by asking the agent.
The DELIVER/SUPPRESS gate#
Running a check is cheap. After the main check produces a result, a small fast model (Claude Haiku) reads it and decides whether it's worth your attention:
- DELIVER — a new issue, a significant change, or actionable information you haven't seen.
- SUPPRESS — a repeat of the last alert, a minor variation, a generic "all clear," or meta-commentary about the heartbeat itself (for example "no checks are configured").
A heartbeat with no configured checks, or one that finds nothing, stays silent — the agent doesn't send "nothing to report" noise.
Controlling the heartbeat#
| Surface | Controls |
|---|---|
| Web UI | Profile page: Start, Stop, Trigger now, edit interval |
| Terminal UI | /heartbeat status \| start \| stop \| trigger \| every <N>m\|<N>h |
| Conversation | Ask the agent to start or stop it, change cadence, or add or remove checks |
If the heartbeat hits repeated errors, the agent backs off and stops the loop rather than spinning on a broken check. A spending-limit error is treated as transient — it skips that tick without counting against the error streak.
Slack-triggered heartbeats#
Heartbeats can also be woken by Slack activity. Designate a Slack channel as a heartbeat trigger from the web UI Channels page, and incoming messages in that channel wake the heartbeat with those messages as context. This lets the agent react to real-time events between scheduled runs.
- A per-channel throttle caps how often this can fire, so a busy channel doesn't trigger the agent constantly.
- Messages are queued and drained atomically, so nothing is lost — even if several arrive while the agent is mid-run, they're picked up on the next pass.
See Slack for the channel setup.
When the agent does deliver, the alert goes to your active conversation and, if configured, broadcasts to connected channels like Slack, labeled as a heartbeat. It reads like any other agent message — the finding, in plain language, with whatever detail the check produced.
For specific work at specific times whose output you always want — reports, reminders, periodic actions — use a scheduled task instead. Use the heartbeat for ongoing monitoring where you only want to hear about it when something's worth reporting.