heartbeat git:20260611.9d7ac6aA

Immutable. This exact content is served forever at /api/v1/blob/cc878a8114ddf2b9.

---
name: heartbeat
description: Run agent heartbeat — periodic checks, memory consolidation, proactive work. Triggers on /agent:heartbeat, "heartbeat", "heartbeat check", "periodic check", "consolidar memoria".
user-invocable: true
---

# Heartbeat

Run the agent's periodic checks. Triggered every 30 minutes by a local cron, or manually.

## How it works

1. **Cron health (ALWAYS — even outside active hours).** This is infrastructure, not a user-facing check; it is what heals orphaned reminders in long-running sessions (see issue #32). This step manages its own state: it reads AND writes the `cronAudit` field of `memory/heartbeat-state.json` itself, here, regardless of whether the later steps run. Every heartbeat:
   - Load the tools once per session if needed: `ToolSearch(query="select:CronList,CronCreate")`.
   - Retire fired one-shots FIRST so the repair below cannot resurrect them:
     `bash "$CLAUDE_PLUGIN_ROOT/skills/crons/writeback.sh" prune-expired`
   - Call `CronList` and pipe its FULL output to:
     `bash "$CLAUDE_PLUGIN_ROOT/skills/crons/writeback.sh" audit`
     (mechanical diff: refreshes `lastSeenAlive`, relinks survivors, prints `orphan key=…` / `blocked key=…` lines and an `audit: alive=K/N …` summary; exit 4 = format drift — stop, surface it, do not create anything).
   - If `orphaned=0` and `blocked=0`: clear `cronAudit.pending` in `memory/heartbeat-state.json` if set — done, say nothing.
   - If `orphaned>0`: repair `orphan key=` lines ONLY (NEVER `blocked key=` lines — those have ambiguous live duplicates; recreating them would add a third copy). `touch "$CLAUDE_PROJECT_DIR/memory/.reconciling"` (the registry's crons are replayed verbatim, so the cron-from.sh stamp gate must be bypassed), then for each orphan key: `CronCreate` with that entry's cron/prompt/recurring from `memory/crons.json` + `writeback.sh set-alive --key <key> --harness-task-id <new id>`; continue past individual failures. Then `rm -f "$CLAUDE_PROJECT_DIR/memory/.reconciling"` immediately and re-run `CronList` → `audit`.
   - **Notification throttle:** write the keys still orphaned-after-repair or blocked into `cronAudit.pending` (with a timestamp) in `memory/heartbeat-state.json`. Notify the user ONLY when the same key(s) were already in `cronAudit.pending` from the previous beat — one notice (orphans: "couldn't re-create X, run /agent:crons reconcile"; blocked: "X has duplicate live reminders, review with /agent:crons list"), then record it as notified so it doesn't repeat every beat.

2. **Check active hours** — read `agent-config.json` for `heartbeat.activeHours`. If outside the window, skip the remaining steps silently (the cron-health step above already ran).

3. **Load state** — read `memory/heartbeat-state.json` (if exists) to know when each check last ran. Avoid repeating checks done less than 30 min ago.

4. **Read HEARTBEAT.md** — this is the checklist. Follow it strictly. Do not infer or repeat old tasks from prior conversations. If nothing in the checklist needs attention, skip to step 7.

5. **Execute checks** — rotate through the items in HEARTBEAT.md, doing 2-4 per heartbeat (not all every time). For each:
   - Memory consolidation: review last 3 daily logs → distill insights → update MEMORY.md
   - Dream review: `dream(action='status')` → note high-recall items not yet promoted
   - Custom checks: whatever the user added to HEARTBEAT.md (emails, health, projects, etc.)

6. **Proactive work** (do without asking):
   - Organize memory files
   - Remove outdated entries from MEMORY.md
   - Check `IMPORT_BACKLOG.md` if it exists — remind user about pending items
   - Verify installed skills are accessible

7. **Update state** — write `memory/heartbeat-state.json` with timestamps for each check performed.

8. **Notify or stay quiet:**
   - If something needs the user's attention → notify (via reply tool if on a messaging channel, or print if CLI)
   - If nothing noteworthy → do nothing. No "heartbeat completed" messages.

## Self-managing the checklist

The agent should **edit HEARTBEAT.md during normal conversations** when something needs periodic attention:

- User says "revísame los emails cada rato" → agent adds `- **Email inbox** — check for urgent unread` to HEARTBEAT.md
- User installs a new skill with periodic needs → agent adds a check for it
- A reminder is due daily → agent adds it to HEARTBEAT.md instead of creating a separate cron
- When a check is no longer needed → agent removes it from HEARTBEAT.md

**Rule:** batch similar checks into HEARTBEAT.md instead of creating multiple cron jobs. Heartbeats are cheaper (one turn, multiple checks) than separate crons (one turn each).

## Active hours

```json
{
  "heartbeat": {
    "activeHours": {
      "start": "08:00",
      "end": "23:00",
      "timezone": "America/Santiago"
    }
  }
}
```

Outside this window, heartbeats skip silently. Configure via `/agent:settings`.

## Scheduling

Created automatically on first session (SessionStart hook):
- Default: `*/30 * * * *` (every 30 minutes)
- Only fires while Claude Code is open and REPL is idle
- For 24/7 heartbeats, use `/agent:service install`