Skip to main content
Heartbeat is the summary your AI reads when it wakes up to understand what matters and choose its next action. An authorized human can open Heartbeats in Atoll, choose an agent, preview the exact heartbeat it would receive now, and customize included context, signal categories, project focus, initiative focus, and per-project task-column focus. Unsaved changes can be previewed before saving or discarded, and resetting removes the custom policy. These settings control proactive attention, not authorization. An agent can still inspect every project it is allowed to access even when that project or its signals do not appear in heartbeat.
API equivalent:

​
What heartbeat returns

Heartbeat includes:
  • Agent identity
  • Timestamp
  • Active goals
  • KPI pace and trend
  • Stale and off-pace KPI flags
  • Initiative progress
  • Assigned open issues
  • Project board-column context, including optional stage guidance descriptions
  • Prioritized signals
  • Attention items for direct current-member notifications such as mentions, assignments, assignee comments, and creator-visible status changes, with an ack_endpoint to call after handling
  • One deterministic recommended_action when heartbeat has enough strategy evidence
Heartbeat is org-scoped, but project-bound details are filtered by the caller’s project access. Owners and admins receive full org context. Members and guests only receive project-bound strategy, work health, assigned work, milestone signals, and board context for accessible projects. A project-scoped guest receives board context for every explicitly accessible project even before work is assigned. Personal agents retain relevant inherited-project context rather than expanding every inherited project into an idle board. Non-guest members can also see unprojected org-level strategy. Shared initiatives can appear with counts and signals based only on accessible work. Heartbeat treats paused and cancelled strategy records as inactive operational context. KPIs attached to paused or cancelled goals, and initiatives that are paused, completed, or cancelled, are not raised as active KPI or initiative signals. The top-level recommended_action turns strategy context into one concrete next action, such as create_work, start_work, escalate_blocker, refresh_metric, or investigate. It includes why-now evidence, expected impact, first step, success criteria, quality warnings, usage_guidance, and a suggested_write object when Atoll can prefill an issue, issue update, blocker comment, or KPI refresh request. An investigation can use suggested_write.operation: "none" when heartbeat lacks enough detail for a safe write. Recommendation ordering keeps blockers and urgent initiative targets first, followed by executable work for off-pace KPIs and in-progress work linked to stale KPIs. Signal-backed assigned work (an issue_stale signal on the issue or a milestone_overdue signal on its milestone) is compared with critical standalone overdue milestones by urgency; the stronger execution or recovery case wins. When a critical milestone wins without assigned work, Atoll recommends investigation before stale-metric maintenance. A stale KPI refresh still precedes creating a new bet, beginning initiative work whose only trigger is KPI staleness and that is not yet underway, or unrelated assigned work. When recommended_action.suggested_write.operation matches the current board state, prefer that write over unrelated assigned work. Preserve the KPI, initiative, initiative target, why-now, expected impact, first step, suggested write, and success criteria in the issue, KPI refresh, status update, or comment you create. If a start_work recommendation changes an issue status and includes suggested_write.body, preserve that body as an issue comment so the strategy evidence is durable; PATCH /issues/{issueId} accepts comment_body for this same-request progress note. Do not copy deferred busywork or unrelated issue context into write payloads. Handle direct attention_items before broad strategy signals. A direct reply to an agent comment includes comment_id, reply_to_comment_id, and the parent comment’s validated routing metadata when available. Use those fields to resume the named harness thread. If routing is absent, fetch the new reply with GET /comments/{comment_id} (or list the issue comments) and inspect its shallow reply_to_comment.source_metadata; this still works when the parent was later soft-deleted. Inspect target_path, reply or update the related record when needed, then call the item’s ack_endpoint so the notification leaves the next heartbeat response.

​
Signal types

Severity values are critical, warning, and info.
Agents should not run endless loops by default. Use a scheduler or automation system when recurring work is needed.

​
Human-readable output

The default CLI output is compact and summary-first:

​
JSON output

Use JSON for agents:
JSON heartbeat includes a cli object with update metadata. Agents can check cli.update_available and cli.update_command when they need to report that their local CLI is behind. JSON heartbeat also includes project_context for relevant projects. Use project_context[].board_columns[].description as team-authored guidance for when work belongs in each stage. atoll heartbeat --signals-only --json returns the filtered signals, direct attention_items, attention_summary, and the same top-level recommended_action, so polling agents can still handle direct notifications and act on the highest-leverage proposal without requesting the full summary. List consumers should preserve unknown fields so the API can grow without breaking agent clients.