---
name: Create Heartbeat
slug: create-heartbeat
category: Automation
description: Create Heartbeat adds a scheduled proactive agent that checks state and decides whether to act. Use it to turn a manual check into an interval-based protocol run with wake triggers and a decision prompt.
github: "https://github.com/evolution-foundation/evo-nexus/tree/main/.claude/skills/create-heartbeat"
language: Python
stars: 523
forks: 176
install: "npx degit https://github.com/evolution-foundation/evo-nexus/tree/main/.claude/skills/create-heartbeat ~/.claude/skills/create-heartbeat"
installs_to: ~/.claude/skills/create-heartbeat
source_path: .claude/skills/create-heartbeat/SKILL.md
collection_size: 25
category_size: 1523
collection_url: "https://dirskills.com/collections/evolution-foundation/evo-nexus"
added: 2026-08-26T05:12:13.698Z
last_synced: 2026-08-26T05:12:13.698Z
canonical_url: "https://dirskills.com/skills/create-heartbeat"
---

# Create Heartbeat

Create Heartbeat adds a scheduled proactive agent that checks state and decides whether to act. Use it to turn a manual check into an interval-based protocol run with wake triggers and a decision prompt.

**Install:**

```bash
npx degit https://github.com/evolution-foundation/evo-nexus/tree/main/.claude/skills/create-heartbeat ~/.claude/skills/create-heartbeat
```

## README

# 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:
   - `atlas-project` — project tracking (Linear, GitHub)
   - `flux-finance` — payments, billing
   - `zara-cs` — support queue
   - `pulse-community` — community sentiment
   - `pixel-social-media` — scheduled posting
2. **How often?** Interval in minutes / hours. Min 60s. Typical: 2h, 4h, 6h.
3. **What state to check?** This becomes the `decision_prompt`.
4. **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`:

```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).