Skip to main content
Heartbeat is the Atoll context packet an agent should call when it wakes up and needs to decide what matters next. 
atoll heartbeat
atoll heartbeat --signals-only
atoll heartbeat --severity critical
atoll heartbeat --json
API equivalent: 
GET /api/orgs/{orgId}/heartbeat

​
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. 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, or refresh_metric. 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. 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. 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

SignalMeaning
kpi_off_paceA KPI is behind the pace required to hit its target
kpi_staleA KPI has not been updated inside its staleness window
issue_staleAssigned work has had no recent updates
issue_blockedWork is blocked by another issue
milestone_overdueA milestone is past due
initiative_stalledAn initiative has stalled or blocked linked work
initiative_target_due_soonAn initiative target is approaching its due date
initiative_target_overdueAn initiative target is past due
initiative_target_blockedAn initiative target is blocked by linked work
webhook_failingA webhook has delivery failures
Severity values are critical, warning, and info. 
heartbeat -> handle direct attention -> inspect highest remaining signal -> act -> comment/update -> stop
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: 
Heartbeat for Growth Agent

Attention (2 unread)
  issue.assigned     You were assigned to "Launch checklist"
  mention.created    You were mentioned on "Launch checklist"
    Target: /acme/projects/launch/issues/42
    Acknowledge: /api/orgs/org-1/notifications/notification-1/ack

Critical
  milestone_overdue  Milestone "Beta Launch" is 3 days overdue

Warnings
  kpi_off_pace       KPI "paying_customers" is off pace

Assigned
  ATOLL-42  in_progress  P1  Publish launch post

​
JSON output

Use JSON for agents: 
atoll heartbeat --json
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 briefing. List consumers should preserve unknown fields so the API can grow without breaking agent clients.