Skill: wyblhl/heartbeat-cron (version 0.4.4)

--- name: heartbeat-cron description: > Create and refine HEARTBEAT.md files for murmur — a CLI daemon that runs scheduled Claude prompts on a cron or interval schedule. Use this skill when the user wants to set up a recurring automated action (e.g., "monitor my GitHub issues", "check Hacker News for AI articles", "watch my endpoints", "send me a daily digest"). Guides the user through an interview, drafts the heartbeat prompt, tests it, and registers it with murmur's scheduler. Triggers: heartbeat, murmur, recurring task, scheduled action, cron, monitor, watch, automate, periodic check, scheduled prompt. metadata: author: t0dorakis version: "0.4.4" --- # Heartbeat Creator Create well-crafted HEARTBEAT.md files for murmur through a structured interview, test run, and refinement loop. ## Context Murmur is a minimal scheduler. It reads a HEARTBEAT.md file, sends its contents to Claude on a schedule, and classifies the response: - `HEARTBEAT_OK` — nothing to report (silent) - `ATTENTION: ...` — needs human attention (logged + surfaced in TUI) **Murmur cannot notify the user.** It only runs the prompt and logs the result. If the user wants notifications (Slack, Telegram, push), the HEARTBEAT.md itself must include the delivery step. The heartbeat is the entire pipeline: gather data → decide → act → deliver. **Each heartbeat is stateless.** Every run is a fresh Claude session with no memory of previous runs. For workflows that need to track changes over time (price deltas, last-checked timestamps), use files in the workspace as simple state stores (e.g., `last-price.txt`, `tracking-state.json`). **Sleep/wake behavior.** When the machine sleeps, the daemon freezes — no ticks fire. On wake, overdue jobs run immediately but multiple missed runs collapse into a single catch-up execution (not one per missed interval). This is correct for heartbeat-style tasks: you want to check current state, not replay missed checks. If the user needs reliable scheduling, advise them to disable sleep on their machine (see FAQ in README). ## HEARTBEAT.md Format Every heartbeat is a markdown file with an optional YAML frontmatter block. Frontmatter values **take precedence** over config.json. ```yaml --- interval: 1h # or cron: "0 9 * * 1-5" (pick one) # tz: America/New_York # timezone for cron (default: local system tz) # timeout: 15m # max run time (default: 5m) # agent: claude-code # "claude-code" (default), "codex", or "pi" # model: opus # model hint passed to the agent # maxTurns: 50 # cap agent iterations per run (default: 99) # name: My Heartbeat # description: What this heartbeat does # session: my-session # pi-specific: reuse a named browser session # sandbox: workspace-write # codex-specific: "read-only", "workspace-write", or "danger-full-access" # networkAccess: false # codex-specific: allow outbound network in workspace-write sandbox # permissions: skip # skip permission checks (only "skip" supported in frontmatter) --- Your prompt here... ``` **Notes:** - `interval` or `cron` — use one, not both. Intervals: `15m`, `1h`, `6h`, `1d`. Cron: standard 5-field expressions. - `permissions: "skip"` is the only permissions value supported in frontmatter. For deny lists, use config.json. - `murmur init` generates a template with these fields pre-filled. ## Workflow ### 0. Preflight Before starting, verify murmur is installed: ```bash which murmur ``` - **Found** → continue to interview. - **Not found** → install via Homebrew: ```bash brew install t0dorakis/murmur/murmur ``` If Homebrew isn't available, install from source: ```bash git clone https://github.com/t0dorakis/murmur.git cd murmur && bun install && bun run build # Then add ./murmur to PATH ``` You can also scaffold a workspace immediately with flags: ```bash murmur init {path} --interval 30m murmur init {path} --cron "0 9 * * 1-5" --timeout 15m murmur init {path} --template github-digest # Use a starter template ``` **Multiple heartbeats per repo** — Use `--name` to create heartbeats in a `heartbeats/` directory: ```bash murmur init {path} --name issue-worker --interval 30m murmur init {path} --name deploy-monitor --cron "0 9 * * 1-5" ``` This creates `heartbeats/<name>/HEARTBEAT.md` inside the workspace. All heartbeats share the repo root as CWD. A root `HEARTBEAT.md` still works alongside named heartbeats. ### 1. Interview Conduct a focused interview using AskUserQuestion. Go one or two questions at a time, building on previous answers. **Round 1 — The goal:** Ask what they want automated. If they're unsure or exploring, read [references/examples.md](references/examples.md) for inspiration across categories: code/repos, research/intelligence, ops/infrastructure, personal/creative. Suggest examples that match their context. **Round 1b — Tool discovery:** Before diving into details, check whether the user's goal needs tools beyond what's already installed. Run a web search to find relevant CLIs, MCP servers, or agent skills that could help. **Browser tools** — Many valuable heartbeats need to interact with real websites (checking prices, monitoring pages, logging into portals). Claude's built-in `WebFetch` works for simple static pages, but sites with JavaScript rendering, login flows, or anti-bot measures need a real browser: - [agent-browser](https://github.com/vercel-labs/agent-browser) — Headless browser CLI for AI agents. Works with Claude Code out of the box. - [pi-browser](https://github.com/badlogic/pi-mono) — Browser extension for pi. Use with `agent: pi`. **Other tools** — Search the web for: `"{user's goal}" CLI tool` or `"{user's goal}" MCP server` or check [skills.sh](https://skills.sh) for community skills. Examples: - Calendar access → Google Calendar MCP or pi-google-calendar extension - Slack/Discord delivery → webhook skills on [skills.sh](https://skills.sh) - GitHub operations → ensure `gh` CLI is installed Tell the user what you found and recommend installing anything that would make the heartbeat more capable. **Round 2 — The details:** Based on their goal, dig into specifics: - What tools/APIs/commands are needed? (gh, curl, specific URLs, API keys) - What's the workspace directory? - How often should it run? Two options: - **Interval** — fixed frequency: `15m`, `1h`, `6h`, `1d` - **Cron** — precise schedule: `0 9 * * 1-5` (weekdays at 9am), `*/30 * * * *` (every 30 min) - If they pick cron, ask about timezone (defaults to local system tz) - Does the heartbeat need more than the default 5-minute timeout? (e.g., `timeout: 15m` for long-running tasks) - Any model preference? (default uses whatever the agent defaults to; can set `model: opus`, `model: sonnet`, etc.) - Agent choice: `claude-code` (default) runs Claude Code CLI; `codex` runs OpenAI Codex CLI (uses sandbox policies); `pi` runs the pi agent (has browser extensions) **Round 3 — Delivery:** This is critical. Ask how they want results delivered. Options: - Write to a file in the workspace (simplest — good default) - Post to Slack/Discord via webhook - Send via Telegram bot API - Create a GitHub issue/comment - Push notification via ntfy.sh - Just use ATTENTION response (user checks TUI/logs) Remind them: murmur is just a scheduler — it won't forward anything. If they want to be notified, the heartbeat itself must do the notifying. **Round 3b — Credentials (if needed):** If delivery or data sources need tokens/webhooks: - Env vars from `.env` in the workspace are available (Bun auto-loads them) - Sensitive values should go in `.env`, referenced as `$VAR_NAME` in the heartbeat ### 2. Draft Write the HEARTBEAT.md file. Rules: - Include a YAML frontmatter block with at least the schedule (`interval` or `cron`). Add `timeout`, `model`, or other fields as needed based on the interview. - Don't include instructions about HEARTBEAT_OK / ATTENTION — the runtime injects those automatically - Be explicit about every step — Claude has no memory between heartbeats - For change-detection workflows (price drops, new items, status changes), include steps to read/write state files in the workspace (e.g., `last-price.txt`, `tracking-state.json`) - Include exact commands with real values (no `{placeholder}` left behind) - Include the delivery step if the user wants notifications - Keep it focused — one purpose per heartbeat - Use `$VAR_NAME` for secrets Place the file at `{workspace}/HEARTBEAT.md` for single-heartbeat workspaces, or `{workspace}/heartbeats/{name}/HEARTBEAT.md` for multi-heartbeat repos. ### 3. Test Run one heartbeat to verify: ```bash murmur beat {workspace_path} # Or for a named heartbeat: murmur beat {workspace_path} --name {name} ``` Show the user the outcome and output. ### 4. Evaluate Ask the user: "Did that do what you expected?" - **No** → refine the HEARTBEAT.md based on feedback, test again. Repeat until satisfied. - **Yes** → proceed to register. ### 5. Register Register the workspace with murmur so the daemon knows about it: 1. Run `murmur init {absolute_workspace_path}` — this auto-registers the workspace in `~/.murmur/config.json` (with `{ path, lastRun: null }`). If HEARTBEAT.md already exists, it skips creating it but still registers. 2. Verify registration: `murmur workspaces list` 3. Schedule, timeout, model, and other settings live in the HEARTBEAT.md frontmatter — no need to edit config.json for these. 4. **Only** edit `~/.murmur/config.json` directly if you need a `permissions.deny` list (frontmatter only supports `permissions: skip`). 5. Tell the user to start the daemon: - `murmur start` — foreground with TUI (press `q` to quit, `d` to detach) - `murmur start --detach` — background mode (reattach with `murmur watch`) ## Rules - Never leave `{placeholder}` values in the final HEARTBEAT.md - Always test with `murmur beat` before declaring done - Always ask the user to evaluate the test result - If a heartbeat needs tools the user doesn't have installed, tell them what to install - One heartbeat = one purpose. Multiple automations in the same repo = use `heartbeats/` directory with `--name`. - Schedule suggestions: `15m` for uptime, `1h` for active dev work, `6h`–`1d` for digests/research. Use cron when the user wants specific times (e.g., `0 9 * * 1-5` for weekday mornings).


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)