\r \r

Heartbeat Creator\r

\r Create well-crafted HEARTBEAT.md files for murmur through a structured interview, test run, and refinement loop.\r \r

Context\r

\r Murmur is a minimal scheduler. It reads a HEARTBEAT.md file, sends its contents to Claude on a schedule, and classifies the response:\r \r

• HEARTBEAT_OK — nothing to report (silent)\r
• ATTENTION: ... — needs human attention (logged + surfaced in TUI)\r \r 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.\r \r 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).\r \r 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).\r \r

HEARTBEAT.md Format\r

\r Every heartbeat is a markdown file with an optional YAML frontmatter block. Frontmatter values take precedence over config.json.\r \r

---\r
interval: 1h # or cron: "0 9 * * 1-5" (pick one)\r
# tz: America/New_York  # timezone for cron (default: local system tz)\r
# timeout: 15m          # max run time (default: 5m)\r
# agent: claude-code    # "claude-code" (default), "codex", or "pi"\r
# model: opus           # model hint passed to the agent\r
# maxTurns: 50          # cap agent iterations per run (default: 99)\r
# name: My Heartbeat\r
# description: What this heartbeat does\r
# session: my-session   # pi-specific: reuse a named browser session\r
# sandbox: workspace-write  # codex-specific: "read-only", "workspace-write", or "danger-full-access"\r
# networkAccess: false  # codex-specific: allow outbound network in workspace-write sandbox\r
# permissions: skip      # skip permission checks (only "skip" supported in frontmatter)\r
---\r
Your prompt here...\r
```\r
\r
**Notes:**\r
\r
- `interval` or `cron` — use one, not both. Intervals: `15m`, `1h`, `6h`, `1d`. Cron: standard 5-field expressions.\r
- `permissions: "skip"` is the only permissions value supported in frontmatter. For deny lists, use config.json.\r
- `murmur init` generates a template with these fields pre-filled.\r
\r
## Workflow\r
\r
### 0. Preflight\r
\r
Before starting, verify murmur is installed:\r
\r
```bash\r
which murmur\r
```\r
\r
- **Found** → continue to interview.\r
- **Not found** → install via Homebrew:\r
  ```bash\r
  brew install t0dorakis/murmur/murmur\r
  ```\r
  If Homebrew isn't available, install from source:\r
  ```bash\r
  git clone https://github.com/t0dorakis/murmur.git\r
  cd murmur && bun install && bun run build\r
  # Then add ./murmur to PATH\r
  ```\r
\r
You can also scaffold a workspace immediately with flags:\r
\r
```bash\r
murmur init {path} --interval 30m\r
murmur init {path} --cron "0 9 * * 1-5" --timeout 15m\r
murmur init {path} --template github-digest   # Use a starter template\r
```\r
\r
**Multiple heartbeats per repo** — Use `--name` to create heartbeats in a `heartbeats/` directory:\r
\r
```bash\r
murmur init {path} --name issue-worker --interval 30m\r
murmur init {path} --name deploy-monitor --cron "0 9 * * 1-5"\r
```\r
\r
This creates `heartbeats/\x3Cname>/HEARTBEAT.md` inside the workspace. All heartbeats share the repo root as CWD. A root `HEARTBEAT.md` still works alongside named heartbeats.\r
\r
### 1. Interview\r
\r
Conduct a focused interview using AskUserQuestion. Go one or two questions at a time, building on previous answers.\r
\r
**Round 1 — The goal:**\r
\r
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.\r
\r
**Round 1b — Tool discovery:**\r
\r
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.\r
\r
**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:\r
\r
- [agent-browser](https://github.com/vercel-labs/agent-browser) — Headless browser CLI for AI agents. Works with Claude Code out of the box.\r
- [pi-browser](https://github.com/badlogic/pi-mono) — Browser extension for pi. Use with `agent: pi`.\r
\r
**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:\r
\r
- Calendar access → Google Calendar MCP or pi-google-calendar extension\r
- Slack/Discord delivery → webhook skills on [skills.sh](https://skills.sh)\r
- GitHub operations → ensure `gh` CLI is installed\r
\r
Tell the user what you found and recommend installing anything that would make the heartbeat more capable.\r
\r
**Round 2 — The details:**\r
\r
Based on their goal, dig into specifics:\r
\r
- What tools/APIs/commands are needed? (gh, curl, specific URLs, API keys)\r
- What's the workspace directory?\r
- How often should it run? Two options:\r
  - **Interval** — fixed frequency: `15m`, `1h`, `6h`, `1d`\r
  - **Cron** — precise schedule: `0 9 * * 1-5` (weekdays at 9am), `*/30 * * * *` (every 30 min)\r
  - If they pick cron, ask about timezone (defaults to local system tz)\r
- Does the heartbeat need more than the default 5-minute timeout? (e.g., `timeout: 15m` for long-running tasks)\r
- Any model preference? (default uses whatever the agent defaults to; can set `model: opus`, `model: sonnet`, etc.)\r
- 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)\r
\r
**Round 3 — Delivery:**\r
\r
This is critical. Ask how they want results delivered. Options:\r
\r
- Write to a file in the workspace (simplest — good default)\r
- Post to Slack/Discord via webhook\r
- Send via Telegram bot API\r
- Create a GitHub issue/comment\r
- Push notification via ntfy.sh\r
- Just use ATTENTION response (user checks TUI/logs)\r
\r
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.\r
\r
**Round 3b — Credentials (if needed):**\r
\r
If delivery or data sources need tokens/webhooks:\r
\r
- Env vars from `.env` in the workspace are available (Bun auto-loads them)\r
- Sensitive values should go in `.env`, referenced as `$VAR_NAME` in the heartbeat\r
\r
### 2. Draft\r
\r
Write the HEARTBEAT.md file. Rules:\r
\r
- 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.\r
- Don't include instructions about HEARTBEAT_OK / ATTENTION — the runtime injects those automatically\r
- Be explicit about every step — Claude has no memory between heartbeats\r
- 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`)\r
- Include exact commands with real values (no `{placeholder}` left behind)\r
- Include the delivery step if the user wants notifications\r
- Keep it focused — one purpose per heartbeat\r
- Use `$VAR_NAME` for secrets\r
\r
Place the file at `{workspace}/HEARTBEAT.md` for single-heartbeat workspaces, or `{workspace}/heartbeats/{name}/HEARTBEAT.md` for multi-heartbeat repos.\r
\r
### 3. Test\r
\r
Run one heartbeat to verify:\r
\r
```bash\r
murmur beat {workspace_path}\r
# Or for a named heartbeat:\r
murmur beat {workspace_path} --name {name}\r
```\r
\r
Show the user the outcome and output.\r
\r
### 4. Evaluate\r
\r
Ask the user: "Did that do what you expected?"\r
\r
- **No** → refine the HEARTBEAT.md based on feedback, test again. Repeat until satisfied.\r
- **Yes** → proceed to register.\r
\r
### 5. Register\r
\r
Register the workspace with murmur so the daemon knows about it:\r
\r
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.\r
2. Verify registration: `murmur workspaces list`\r
3. Schedule, timeout, model, and other settings live in the HEARTBEAT.md frontmatter — no need to edit config.json for these.\r
4. **Only** edit `~/.murmur/config.json` directly if you need a `permissions.deny` list (frontmatter only supports `permissions: skip`).\r
5. Tell the user to start the daemon:\r
   - `murmur start` — foreground with TUI (press `q` to quit, `d` to detach)\r
   - `murmur start --detach` — background mode (reattach with `murmur watch`)\r
\r
## Rules\r
\r
- Never leave `{placeholder}` values in the final HEARTBEAT.md\r
- Always test with `murmur beat` before declaring done\r
- Always ask the user to evaluate the test result\r
- If a heartbeat needs tools the user doesn't have installed, tell them what to install\r
- One heartbeat = one purpose. Multiple automations in the same repo = use `heartbeats/` directory with `--name`.\r
- 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).\r