create-heartbeat

Create Heartbeat

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

Create a new heartbeat — a proactive agent that wakes on a schedule, runs the 9-step protocol, and decides whether to act.

When to use

Use heartbeats when:

• The agent should check state and conditionally act (e.g., Atlas checks Linear for blockers)
• You want no work when state is calm (vs routines which always run)
• The same topic is picked from an inbox of tickets (heartbeats query tickets in step 3)

Don't use heartbeats for:

• Deterministic scheduled jobs (use a routine)
• One-off actions (use a skill or ticket)

Step 1: Understand the trigger

Ask the user:

1. Which agent? List agents from .claude/agents/*.md. Suggest by domain:
2. atlas-project — project tracking (Linear, GitHub)
3. flux-finance — payments, billing
4. zara-cs — support queue
5. pulse-community — community sentiment
6. pixel-social-media — scheduled posting
7. How often? Interval in minutes / hours. Min 60s. Typical: 2h, 4h, 6h.
8. What state to check? This becomes the decision_prompt.
9. Link to a goal? Optional goal_id for context injection. Skip if no goal fits.

Step 2: Compose the decision prompt

The decision_prompt is injected into the agent's context and asks the agent:

"Given the current state of [X], should you act? If yes, do the work and report. If no, explain briefly and skip."

Good decision prompts are specific:

✅ "Check Linear for issues in In Progress assigned to an unresponsive person (> 48h inactive) or blocked > 24h. If any, create action items and notify Davidson. Otherwise skip."

❌ "Check stuff" (too vague — will always act or always skip randomly)

Step 3: Pick wake triggers

Default: interval + manual. Optional:

• new_task — wake when a ticket is assigned
• mention — wake when @<agent-slug> appears in a comment
• approval_decision — wake when an approval affects this agent

30s debounce prevents multiple triggers coalescing into multiple runs.

Step 4: Required secrets (optional)

If the decision/work requires API keys (Stripe, Linear, etc.), list them as required_secrets. They'll be validated at startup (presence, not value).

Step 5: Write to YAML

Append the new heartbeat to config/heartbeats.yaml:

heartbeats:
  - id: <agent-slug>-<interval>h
    agent: <agent-slug>
    interval_seconds: <N>
    max_turns: 10
    timeout_seconds: 600
    lock_timeout_seconds: 1800
    wake_triggers: [interval, manual]
    enabled: false            # opt-in — user enables after testing
    goal_id: null
    required_secrets: []
    decision_prompt: |
      <the prompt from step 2>

Validate with make heartbeat-lint before suggesting the user enables.

Step 6: Guide the user

After writing:

1. Run make heartbeat-lint to validate
2. Test manually: UI /scheduler → Heartbeats tab → Run Now on this heartbeat
3. Review the run in workspace/ADWs/logs/heartbeats/<id>-<date>.jsonl
4. If the decision quality is right, flip enabled: true and restart dashboard

Notes

• Source of truth is the YAML. UI CRUD rewrites it atomically (temp file + rename).
• Delete a heartbeat via /scheduler → Heartbeats → Delete, or remove the entry from YAML and restart.
• Heartbeat cost appears in /costs once runs start generating heartbeat_runs rows.

Related: .claude/rules/heartbeats.md, .claude/rules/tickets.md (inbox), .claude/rules/goals.md (context).