manage-heartbeats

name	manage-heartbeats
description	List, enable, disable, or manually trigger heartbeats (proactive agents). Shows last 10 runs with status and cost. Use when the user says 'list heartbeats', 'show active heartbeats', 'enable atlas-4h', 'disable zara-2h', 'run atlas heartbeat now', 'which heartbeats are running', or wants visibility into proactive agent state.

Manage Heartbeats

Auth note: Use from dashboard.backend.sdk_client import evo — auto-handles URL + auth, no Bearer token needed in code.

Inspect and control existing heartbeats — list them, enable/disable, trigger manual runs, review run history.

When to use

Use this skill when the user wants to:

• See which heartbeats exist and their status
• Enable a heartbeat they set up but left disabled
• Disable a heartbeat that's costing too much or misbehaving
• Manually trigger a run (outside the normal interval)
• Review recent runs and decide if the heartbeat is working

Don't use this to create new heartbeats — use /create-heartbeat.

Step 1: List all heartbeats

from dashboard.backend.sdk_client import evo
heartbeats = evo.get("/api/heartbeats")

Response shape per heartbeat: id, agent, interval_seconds, enabled, last_run_at, last_run_status, last_run_cost_usd, next_trigger_at.

Present to user as a table:

• ID
• Agent
• Status (enabled / disabled)
• Interval (human format: "every 4h")
• Last run (time + status)
• Cost 7d (sum of cost_usd in last 7 days)

Step 2: Detailed view (one heartbeat)

from dashboard.backend.sdk_client import evo
hb = evo.get(f"/api/heartbeats/{hb_id}")

Includes last 10 runs with full fields: started_at, ended_at, duration_ms, tokens_in, tokens_out, cost_usd, status, prompt_preview, error.

Show the user the latest 3 runs, summarize patterns (always-skip / always-act / mixed).

Step 3: Enable / disable

from dashboard.backend.sdk_client import evo

# Enable
evo.patch(f"/api/heartbeats/{hb_id}", {"enabled": True})

# Disable (preserves data, just stops the dispatcher from scheduling)
evo.patch(f"/api/heartbeats/{hb_id}", {"enabled": False})

Warn the user:

• Enable doesn't run immediately — next trigger fires at the top of the next interval.
• Disable doesn't cancel a currently-running execution.

Step 4: Run Now (manual trigger)

from dashboard.backend.sdk_client import evo
result = evo.post(f"/api/heartbeats/{hb_id}/run")

Response {"run_id": "...", "status": "queued"} within ~500ms. Execution happens async.

Tell the user:

• Run logs appear in workspace/ADWs/logs/heartbeats/<id>-<date>.jsonl in real time.
• Or poll GET /api/heartbeats/<id> to see last_run_status flip from running → success / fail / timeout.

Step 5: Paginated run history

from dashboard.backend.sdk_client import evo
runs = evo.get(f"/api/heartbeats/{hb_id}/runs", params={"limit": 50})

Useful to audit a heartbeat that was misbehaving historically. Filter by:

• ?status=fail — only failures
• ?status=timeout — only timeouts
• ?from=YYYY-MM-DD&to=YYYY-MM-DD — date range

Step 6: Delete (rare)

Only if truly obsolete:

from dashboard.backend.sdk_client import evo

# Gracefully — returns 409 if currently running
evo.delete(f"/api/heartbeats/{hb_id}")

# Force-kill currently-running
evo.delete(f"/api/heartbeats/{hb_id}", params={"force": "true"})

Confirm with user before forcing. Disable first, then delete once runs stop.

Notes

• UI equivalent: /scheduler → Heartbeats tab. The skill is useful for scripted management or when Davidson prefers CLI.
• Cost visibility: /costs shows heartbeat cost per agent alongside routine costs.

Related: .claude/rules/heartbeats.md, /create-heartbeat.