# Heartbeat

> Manage and schedule recurring workspace heartbeats and database-bound reminders.

- Skill: `octaviantocan/heartbeat` (Agent Skill)
- Install (CLI): `npx skillmds@latest add octaviantocan/heartbeat`
- Raw SKILL.md: https://api.skillmd.com/api/skills/octaviantocan/heartbeat/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: octaviantocan (https://skillmd.com/u/octaviantocan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/octaviantocan/heartbeat

---


# Heartbeat & Reminder Scheduler

Use this skill when the user wants to schedule recurring agent tasks, automated check-ins, or simple reminders.

## 1. Choosing the Right Mechanism

When the user asks to schedule something, choose the appropriate system:

*   **`HEARTBEAT.md` (Workspace-Scoped, Permanent)**: Use this for structured, workspace-bound recurring agent prompts (e.g., weekly project summaries, morning inbox triage, or build-status checks). These are checked into Git, shared with other team members/agents in the workspace, and support global text guidelines.
*   **Database Reminders (Personal, Transient)**: Use this for personal, lightweight, or one-shot conversational reminders (e.g., *"remind me to check X in 2 hours"* or *"remind me about Y tomorrow"*). This is done purely through the `reminder_schedule` tool, bypassing files and manual syncing.

---

## 2. Modifying the Heartbeat (`HEARTBEAT.md`)

When updating workspace-scoped heartbeat checks:

### Step 1: Read the Existing Config
Open and inspect `HEARTBEAT.md` at the workspace root to check for existing cron checks.
*   If the file does not exist, initialize it with a markdown title and the YAML front-matter fences.

### Step 2: Formulate the Cron Check
Construct the cron check dictionary with the following schema keys:
*   `name`: Unique, lowercase, and **strictly no whitespace** (e.g., `morning_pulse`).
*   `cron`: A valid 5-field cron trigger string (validated at parse time).
*   `prompt`: The self-contained instruction/prompt for the agent when it fires.

### Step 3: Write to File
*   Write or update the check in the YAML front matter of `HEARTBEAT.md`.
*   Preserve all pre-existing checks.
*   Optional: If the user provides general guidance on *how* checks should behave (e.g., *"ignore emails from automated senders"*), append it to the markdown body below the front matter so the agent reads it contextually when any check executes.

### Step 4: Instruct the User to Sync
The agent does not have direct sync tool permissions. Once the file is updated, tell the user:
> "I've successfully updated `HEARTBEAT.md` with your new schedule. Please click the **Sync** button in the Settings UI (or send a POST to `/api/v1/heartbeat/sync`) to activate the new schedules in the job database."

---

## 3. Scheduling Database Reminders

When the user wants simple reminders (one-shot or chat-only recurring tasks):
1. Use `reminder_list` to check if a similar schedule already exists.
2. Invoke `reminder_schedule` with a descriptive name, prompt, and either `cron_expression` or `fire_at`.
3. Inform the user of success and print the registered Job UUID.