<!-- source: https://deepwiki.com/qhkm/zeptoclaw/11.3-heartbeatservice -->

# HeartbeatService

- src/channels/manager.rs
- src/channels/types.rs
- src/cli/gateway.rs
- src/cron/mod.rs
- src/heartbeat/mod.rs
- src/heartbeat/service.rs
- src/plugins/watcher.rs

The **HeartbeatService** is a background service that periodically checks a workspace file (`HEARTBEAT.md`) for actionable content and dispatches prompts to the agent when tasks are detected. It provides a lightweight mechanism for scheduled agent wake-ups without requiring the full complexity of the persistent `CronService`.

## Purpose and Architecture

HeartbeatService monitors a designated file (typically `HEARTBEAT.md` in the user's workspace) at regular intervals. When the file contains actionable content—defined as non-empty lines that are not comments or headers—the service publishes an `InboundMessage` to the `MessageBus` [src/heartbeat/service.rs12-18](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L12-L18) This triggers the `AgentLoop` to process the tasks listed in the file.

**Key characteristics:**

- Polling-based : Uses a tokio::time::interval timer rather than filesystem watchers src/heartbeat/service.rs 129-133
- Actionability detection : Skips empty files, Markdown headers, HTML comments, and bare checkbox syntax src/heartbeat/service.rs 188-200
- Message bus integration : Dispatches via MessageBus::publish_inbound src/heartbeat/service.rs 228-233
- Health tracking : Monitors consecutive failures and exposes health status to the HealthRegistry src/heartbeat/service.rs 142-152

**Sources:** [src/heartbeat/service.rs1-19](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L1-L19) [src/heartbeat/service.rs67-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L67-L78) [src/cli/gateway.rs18-24](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L18-L24)

## Component Architecture

The following diagram illustrates how the `HeartbeatService` interacts with the configuration, the filesystem, and the message bus.

### System Entity Mapping

### Service Interaction Diagram

```

```

**Sources:** [src/heartbeat/service.rs67-78](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L67-L78) [src/heartbeat/service.rs128-156](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L128-L156) [src/cli/gateway.rs18-24](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L18-L24)

## Heartbeat Tick Flow

The service operates on a loop. On every "tick", it evaluates the state of the heartbeat file and decides whether to wake the agent.

```

```

**Sources:** [src/heartbeat/service.rs128-156](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L128-L156) [src/heartbeat/service.rs202-237](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L202-L237)

## Actionability detection ( is_empty )

The `is_empty()` logic ensures the agent isn't woken up for boilerplate or metadata. It parses the file line-by-line [src/heartbeat/service.rs188-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L188-L200)

The following are ignored:

1. Whitespace : Trimmed lines that result in an empty string.
2. Headers : Lines starting with # (Markdown levels).
3. Comments : Lines starting with <!-- (HTML/Markdown comments).
4. Empty Checkboxes : Specific patterns - [ ] and * [ ] .

If any line remains after these filters, the file is considered **actionable**, and a message is dispatched [src/heartbeat/service.rs197-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L197-L200)

**Sources:** [src/heartbeat/service.rs188-200](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L188-L200)

## Health Tracking and Failures

The service tracks its own health to ensure the gateway can report if background monitoring has stalled.

- Consecutive Failures : Tracked via an AtomicU32 src/heartbeat/service.rs 75
- Failure Threshold : Defaults to 3 src/heartbeat/service.rs 97
- Warning : If failures reach the threshold, a warn! log is emitted indicating the service may be degraded src/heartbeat/service.rs 144-149
- Health Check : The is_healthy() method returns false if the threshold is exceeded src/heartbeat/service.rs 183-185

**Sources:** [src/heartbeat/service.rs141-152](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L141-L152) [src/heartbeat/service.rs183-185](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L183-L185)

## Gateway Integration

The `HeartbeatService` is typically initialized during the `cmd_gateway` startup sequence if enabled in the configuration [src/cli/gateway.rs304-340](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L304-L340)

1. Bootstrap : The gateway calls ensure_heartbeat_file() to create the file from HEARTBEAT_TEMPLATE if it is missing src/heartbeat/mod.rs 7
2. Initialization : It parses the deliver_to configuration (e.g., "telegram:12345" ) into a channel and chat ID.
3. Lifecycle : The service is wrapped in an Arc and started. It is stopped gracefully when the gateway receives a shutdown signal.

**Sources:** [src/cli/gateway.rs18-24](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/gateway.rs#L18-L24) [src/heartbeat/service.rs102-159](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L102-L159)

## Comparison: Heartbeat vs. Cron

ZeptoClaw provides two mechanisms for background tasks.

**Sources:** [src/heartbeat/service.rs1-19](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/heartbeat/service.rs#L1-L19) [src/cron/mod.rs17-57](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cron/mod.rs#L17-L57)
