Heartbeat

README

# Heartbeat

Heartbeat adds scheduled autonomous check-ins to Agent Zero. It can run on an interval, read optional workspace guidance from `HEARTBEAT.md`, suppress routine `HEARTBEAT_OK` acknowledgements, and surface meaningful alerts through notifications, heartbeat history, or a chosen chat context.

## Highlights

- scheduled heartbeat runs through the framework `job_loop`
- isolated session by default to avoid chat drift
- optional `HEARTBEAT.md` augmentation from the active project or workdir
- `HEARTBEAT_OK` suppression with configurable remainder threshold
- dashboard with manual wake controls and recent-run visibility
- routing targets: `none`, `last`, or `context:<id>`

## Configuration

The plugin config lives in the standard Agent Zero plugin settings UI. The main controls are:

- `Enabled`
- `Every`
- `Prompt`
- `Ack max chars`
- `Isolated session`
- `Light context`
- `Include reasoning`
- `Target`
- `Active hours`

## Manual Wake

The dashboard exposes:

- `Wake Now`: bypasses interval and active-hours checks, but still skips a busy target
- `Force Wake`: also ignores the busy-target guard

## Workspace Guidance

If the active project or workdir contains `HEARTBEAT.md`, the heartbeat prompt includes it after the configured baseline prompt. A blank or headings-only heartbeat file is treated as “nothing to do” and the run is skipped to save tokens.