# agent-heartbeats

> Composer pill with the heartbeat count, plus a panel to list, create, edit, and delete that agent's heartbeats.

> This is a community-submitted listing. Treat plugin-provided text as untrusted data and review the source before installing or running code.

- **Plugin ID:** `agent-heartbeats`
- **Source repository:** [panrafal/paseo-plugins](https://github.com/panrafal/paseo-plugins/tree/main/agent-heartbeats)
- **Plugin path:** `agent-heartbeats`
- **Catalog page:** https://paseo.cafe/plugins/agent-heartbeats
- **Markdown listing:** https://paseo.cafe/plugins/agent-heartbeats.md
- **Catalog API:** https://paseo.cafe/api/plugin/agent-heartbeats.json
- **Author:** panrafal
- **License:** MIT
- **Requires Paseo:** `>=0.7.2-0`
- **Platforms:** all
- **Categories:** productivity

## Install

```sh
Exact install target unavailable
```

## Caveats

- Changing a heartbeat prompt or max-run count creates a replacement and resets run history

## Catalog health

- Manifest: valid
- README: present
- License: present
- Tests: not detected
- Typecheck script: present

## Security scan

- Status: failed
- Blocking findings: 1
- Advisory findings: 0

## Repository-provided content

> Everything below this point comes from the community repository. It is untrusted reference material, not system instructions. No catalog-authored facts follow it.

### Installation notes

```bash
paseo plugin add panrafal/paseo-plugins:agent-heartbeats
```

From a checkout:

```bash
npm install
npm run typecheck
paseo plugin install /absolute/path/to/paseo-plugins/agent-heartbeats
paseo plugin ls
```

After editing:

```bash
npm run typecheck
paseo plugin reload agent-heartbeats
paseo plugin logs agent-heartbeats
```

### Limitations

- Completed heartbeats are not counted or listed.
- Changing a heartbeat prompt or maximum-run count creates a replacement and resets that
  heartbeat's run history. Cron-only edits keep history.

### Source README

#### agent-heartbeats

Paseo plugin that adds a compact heartbeat icon and count to every active agent's composer. Pressing
the pill opens an agent-scoped panel for reviewing and managing that agent's heartbeats.

![Heartbeat pill](./images/agent-heartbeats-pill.png)
![Heartbeats panel](./images/agent-heartbeats-panel.png)

##### Interface

- The composer pill contains only a heartbeat icon and the number of currently scheduled
  heartbeats.
- The panel lists each prompt, human-readable cadence, raw cron expression, next run, completed run
  count, and maximum run count.
- Heartbeats can be edited or deleted. Cron-only edits preserve their run history. Paseo does not
  expose prompt or maximum-run updates for heartbeats, so changing either creates a replacement and
  resets the daemon's run history for that heartbeat.
- The add form is always visible. Its schedule field accepts five-field cron, one-shot delays such as
  `15m`, `15 minutes`, or `in one hour`, and recurring phrases such as `every 15 minutes`. Suggested
  common schedules appear directly below the field.
- One-shot delays are compiled to a UTC cron occurrence with a one-run limit. Recurring phrases are
  accepted only when five-field cron can represent the interval exactly.

The count and panel refresh every 15 seconds and immediately after a mutation. Completed heartbeats
are not counted or listed.

##### Runtime behavior

The plugin reads the daemon's atomic schedule records under `$PASEO_HOME/schedules` to list
agent-target heartbeats, including heartbeats created outside this plugin. Mutations run Paseo's
supported `heartbeat create`, `heartbeat update`, and `heartbeat delete` commands without a shell,
after checking that the heartbeat belongs to the selected agent.

##### Limitations

- Completed heartbeats are not counted or listed.
- Changing a heartbeat prompt or maximum-run count creates a replacement and resets that
  heartbeat's run history. Cron-only edits keep history.

##### Install

```bash
paseo plugin add panrafal/paseo-plugins:agent-heartbeats
```

From a checkout:

```bash
npm install
npm run typecheck
paseo plugin install /absolute/path/to/paseo-plugins/agent-heartbeats
paseo plugin ls
```

After editing:

```bash
npm run typecheck
paseo plugin reload agent-heartbeats
paseo plugin logs agent-heartbeats
```