@e9n/pi-heartbeat

Periodic health check extension for pi. Runs a configurable prompt as an isolated subprocess on an interval and alerts via pi-channels when something needs attention.

Features

• Spawns a pi --no-session subprocess to run health checks in isolation
• Reads HEARTBEAT.md from cwd as a per-project checklist; falls back to a generic check if missing
• Suppresses HEARTBEAT_OK responses; escalates anything else as an alert via pi-channels
• Delivers alerts via the channel:send event (integrates with pi-channels)
• Optional persistent run history via pi-kysely
• Web dashboard at /heartbeat via pi-webserver
• Disabled by default — enable with --heartbeat flag, /heartbeat on, or autostart: true

Setup / Settings

Add to ~/.pi/agent/settings.json (global) or .pi/settings.json (project):

{
  "pi-heartbeat": {
    "autostart": false,
    "intervalMinutes": 15,
    "activeHours": { "start": "08:00", "end": "22:00" },
    "route": "ops",
    "showOk": false,
    "prompt": null,
    "webui": false,
    "useKysely": false,
    "extensions": null
  }
}

Key	Default	Description
autostart	false	Start automatically on session start.
intervalMinutes	15	Minutes between checks.
activeHours	{"start":"08:00","end":"22:00"}	Only run checks inside this window. null for 24/7.
route	"ops"	pi-channels route for alert delivery.
showOk	false	Also send a notification on HEARTBEAT_OK (not just alerts).
prompt	null	Custom prompt override — bypasses HEARTBEAT.md.
webui	false	Mount web dashboard on pi-webserver at /heartbeat.
useKysely	false	Persist run history via pi-kysely instead of in-memory.
extensions	null	Extensions to load in the subprocess. null = none.

HEARTBEAT.md

Place a HEARTBEAT.md in your project root with a checklist of things to verify:

# Heartbeat Checklist

- Check that the API server responds on port 3000
- Verify database connectivity
- Confirm disk usage is below 90%

If the file is missing or contains only headers/blank lines, checks are skipped.

Commands

Command	Description
/heartbeat on	Start periodic checks
/heartbeat off	Stop checks
/heartbeat status	Show interval, run count, OK/alert totals, last result
/heartbeat run	Run a check immediately

Pass --heartbeat at startup to enable automatically: pi --heartbeat.

Web UI

Enable with "webui": true. Requires pi-webserver ("pi-webserver": { "autostart": true }).

Dashboard at http://localhost:4100/heartbeat — live status, stats (runs / OK / alerts / rate), last check result, expandable history (up to 100 entries), and start / stop / run controls.

REST API at /api/heartbeat:

Method	Body	Description
GET	—	Status, stats, and history
POST	{ "action": "start" }	Start heartbeat
POST	{ "action": "stop" }	Stop heartbeat
POST	{ "action": "run" }	Run a check immediately

Events

Event	Payload	Description
heartbeat:check	{ time }	Emitted when a check starts
heartbeat:result	{ ok, response, durationMs, time }	Emitted when a check completes
channel:send	{ route, text, source: "pi-heartbeat" }	Alert dispatched to pi-channels

Install

pi install npm:@e9n/pi-heartbeat

License

MIT