Heartbeat Tasks

Overview

Heddle can wake on a schedule, do limited work, checkpoint results, and decide whether to continue, pause, complete, or escalate to you. Each cycle is bounded so the agent never runs away unchecked.

The heartbeat CLI uses the same server-backed scheduler model as the browser task workbench. It attaches to a live control-plane server when one exists, or starts an embedded server when needed, so terminal commands and browser controls share durable task records, run history, continuation state, model settings, and step budgets.

What is a heartbeat task?

A heartbeat task is a durable local agent task with an instruction, schedule interval, optional model, optional step budget, continuation mode, checkpoints, and saved run records. It is meant for operator-controlled background work such as repository gardening, recurring checks, monitoring, or periodic documentation cleanup.

Runner cycle

1. Load the durable task and prior checkpoint.
2. Resume prior transcript state when available.
3. Let the agent do bounded useful work within the configured budget.
4. Checkpoint the new state and save a run record.
5. Return a decision: continue, pause, complete, or escalate.

Continuation and limits

Tasks can use operator-controlled continuation or agent-selected continuation. A blocked or paused task must be resumed explicitly instead of silently unblocking on every manual run. Adding a heartbeat task saves scheduler state; it does not install a hidden OS background service. Keep a scheduler host running with heddle heartbeat start when you want recurring execution.

Commands

heddle heartbeat start --every 30m --task "Check for safe maintenance work"

heddle heartbeat task add --id repo-gardener \
  --task "Check for safe maintenance work" \
  --every 1h

heddle heartbeat task list
heddle heartbeat task show repo-gardener
heddle heartbeat run --task repo-gardener
heddle heartbeat runs list --task repo-gardener
heddle heartbeat runs show latest --task repo-gardener