heartbeat-cron

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Heartbeat Creator

Heartbeat 生成器

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

通过结构化访谈、测试运行和优化循环，为murmur创建规范的HEARTBEAT.md文件。

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

Murmur是一款轻量型调度器。它会读取HEARTBEAT.md文件，按照预设计划将文件内容发送给Claude，并对返回结果进行分类：

```
HEARTBEAT_OK
```
— 无内容需汇报（静默状态）
```
ATTENTION: ...
```
— 需要人工关注（会被记录并在TUI中显示）

Murmur无法直接通知用户。它仅负责运行提示词并记录结果。如果用户需要通知（如Slack、Telegram、推送通知），HEARTBEAT.md文件本身必须包含通知发送步骤。Heartbeat是完整的流程：收集数据 → 决策 → 执行 → 交付结果。

每个Heartbeat都是无状态的。每次运行都是全新的Claude会话，不会保留之前运行的记忆。对于需要跟踪随时间变化的工作流（如价格变动、上次检查时间戳），可使用工作区中的文件作为简单的状态存储（例如

last-price.txt

、

tracking-state.json

）。

休眠/唤醒行为。当机器进入休眠状态时，守护进程会暂停——不会触发任何任务。唤醒后，逾期的任务会立即运行，但多次错过的任务会合并为一次补执行（不会按错过的次数分别执行）。这符合heartbeat类任务的需求：你需要检查当前状态，而非重新执行错过的检查。如果用户需要可靠的调度，建议他们禁用机器的休眠功能（详见README中的FAQ）。

HEARTBEAT.md Format

HEARTBEAT.md 格式

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)

每个heartbeat都是一个Markdown文件，可选择性包含YAML前置块。前置块中的配置值优先级高于config.json。

yaml

---
interval: 1h # 或使用 cron: "0 9 * * 1-5"（二选一）

tz: America/New_York # timezone for cron (default: local system tz)

tz: America/New_York # cron计划的时区（默认：本地系统时区）

timeout: 15m # max run time (default: 5m)

timeout: 15m # 最长运行时间（默认：5分钟）

agent: claude-code # "claude-code" (default), "codex", or "pi"

agent: claude-code # 可选值："claude-code"（默认）、"codex"或"pi"

model: opus # model hint passed to the agent

model: opus # 传递给agent的模型提示

maxTurns: 50 # cap agent iterations per run (default: 99)

maxTurns: 50 # 每次运行的agent迭代次数上限（默认：99）

name: My Heartbeat

description: What this heartbeat does

description: 此heartbeat的功能说明

session: my-session # pi-specific: reuse a named browser session

session: my-session # pi专属：复用已命名的浏览器会话

sandbox: workspace-write # codex-specific: "read-only", "workspace-write", or "danger-full-access"

sandbox: workspace-write # codex专属：可选值"read-only"、"workspace-write"或"danger-full-access"

networkAccess: false # codex-specific: allow outbound network in workspace-write sandbox

networkAccess: false # codex专属：在workspace-write沙箱中允许出站网络访问

permissions: skip # skip permission checks (only "skip" supported in frontmatter)

permissions: skip # 跳过权限检查（前置块中仅支持"skip"值）

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.

你的提示词内容...


**注意事项：**

- `interval`或`cron`——二选一，不可同时使用。间隔格式：`15m`、`1h`、`6h`、`1d`。Cron：标准5字段表达式。
- `permissions: "skip"`是前置块中唯一支持的权限配置值。如需设置拒绝列表，请使用config.json。
- `murmur init`命令会生成包含这些字段的模板文件。

Workflow

工作流程

0. Preflight

0. 预检查

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.

开始之前，请确认murmur已安装：

bash

which murmur

已找到 → 继续访谈流程。

未找到 → 通过Homebrew安装：

bash

brew install t0dorakis/murmur/murmur

如果没有Homebrew，可从源码安装：

bash

git clone https://github.com/t0dorakis/murmur.git
cd murmur && bun install && bun run build
# 然后将./murmur添加到系统PATH中

你也可以通过参数直接快速搭建工作区：

bash

murmur init {path} --interval 30m
murmur init {path} --cron "0 9 * * 1-5" --timeout 15m
murmur init {path} --template github-digest   # 使用预置模板

一个仓库中配置多个heartbeat —— 使用

--name

参数在

heartbeats/

目录下创建heartbeat：

bash

murmur init {path} --name issue-worker --interval 30m
murmur init {path} --name deploy-monitor --cron "0 9 * * 1-5"

这会在工作区中创建

heartbeats/<name>/HEARTBEAT.md

文件。所有heartbeat共享仓库根目录作为工作目录。根目录下的HEARTBEAT.md可与命名heartbeat共存。

1. Interview

1. 访谈流程

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 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 — Headless browser CLI for AI agents. Works with Claude Code out of the box.
pi-browser — Browser extension for pi. Use with
```
agent: pi
```
.

Other tools — Search the web for:

"{user's goal}" CLI tool

"{user's goal}" MCP server

or check skills.sh for community skills. Examples:

Calendar access → Google Calendar MCP or pi-google-calendar extension
Slack/Discord delivery → webhook skills on 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

使用AskUserQuestion进行针对性访谈，每次提问1-2个问题，根据之前的回答逐步深入。

第一轮 — 明确目标：

询问用户想要自动化的任务。如果用户不确定或需要灵感，可参考references/examples.md中的分类示例：代码/仓库、研究/情报、运维/基础设施、个人/创意类。根据用户的场景推荐合适的示例。

第一轮补充 — 工具发现：

在深入细节之前，检查用户的目标是否需要额外的工具。通过网络搜索找到相关的CLI工具、MCP服务器或agent技能来辅助实现。

浏览器工具 —— 许多实用的heartbeat需要与真实网站交互（如检查价格、监控页面、登录门户）。Claude内置的

WebFetch

适用于简单的静态页面，但对于需要JavaScript渲染、登录流程或反爬机制的网站，需要使用真实浏览器：

agent-browser —— 面向AI agent的无头浏览器CLI，可直接与Claude Code配合使用。
pi-browser —— 适用于pi的浏览器扩展，需配合
```
agent: pi
```
使用。

其他工具 —— 在网络上搜索：

"{用户目标}" CLI工具

或

"{用户目标}" MCP服务器

，或查看skills.sh上的社区技能。示例：

日历访问 → Google Calendar MCP或pi-google-calendar扩展
Slack/Discord消息推送 → skills.sh上的webhook技能
GitHub操作 → 确保已安装
```
gh
```
CLI

将搜索结果告知用户，并推荐安装可提升heartbeat能力的工具。

第二轮 — 细节确认：

根据用户的目标，深入确认具体细节：

需要使用哪些工具/API/命令？（如gh、curl、特定URL、API密钥）
工作区目录是什么？
运行频率？有两种选择：
- 固定间隔 —— 固定频率：
```
15m
```
  、
```
1h
```
  、
```
6h
```
  、
```
1d
```
- Cron计划 —— 精确的时间计划：
```
0 9 * * 1-5
```
  （工作日上午9点）、
```
*/30 * * * *
```
  （每30分钟）
- 如果用户选择cron，询问时区（默认：本地系统时区）
heartbeat是否需要超过默认5分钟的超时时间？（例如：长时间运行的任务可设置
```
timeout: 15m
```
）
模型偏好？（默认使用agent的默认模型；可设置
```
model: opus
```
、
```
model: sonnet
```
等）
Agent选择：
```
claude-code
```
（默认）运行Claude Code CLI；
```
codex
```
运行OpenAI Codex CLI（遵循沙箱策略）；
```
pi
```
运行pi agent（支持浏览器扩展）

第三轮 — 结果交付：

这是关键环节。询问用户希望如何接收结果。可选方式：

写入工作区中的文件（最简单的方式——推荐默认使用）
通过webhook发送到Slack/Discord
通过Telegram Bot API发送
创建GitHub议题/评论
通过ntfy.sh发送推送通知
仅使用ATTENTION响应（用户通过TUI/日志查看）

提醒用户：murmur只是调度器——它不会主动转发任何内容。如果用户需要接收通知，heartbeat本身必须包含通知发送逻辑。

第三轮补充 — 凭证（如有需要）：

如果结果交付或数据来源需要令牌/webhook：

工作区中
```
.env
```
文件里的环境变量可直接使用（Bun会自动加载）
敏感值应存储在
```
.env
```
中，在heartbeat中通过
```
$VAR_NAME
```
引用

2. Draft

2. 起草文件

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.

编写HEARTBEAT.md文件。规则：

包含YAML前置块，至少包含计划配置（
```
interval
```
或
```
cron
```
）。根据访谈结果添加
```
timeout
```
、
```
model
```
或其他字段。
无需包含HEARTBEAT_OK / ATTENTION相关说明——运行时会自动注入这些逻辑
明确每一个步骤——Claude在不同heartbeat运行之间没有记忆
对于变更检测工作流（如价格下降、新内容、状态变更），需包含读取/写入工作区状态文件的步骤（例如
```
last-price.txt
```
、
```
tracking-state.json
```
）
包含带有真实值的精确命令（不要留下
```
{placeholder}
```
占位符）
如果用户需要通知，包含结果交付步骤
保持聚焦——每个heartbeat对应一个功能
使用
```
$VAR_NAME
```
表示敏感信息

对于单heartbeat工作区，将文件放在

{workspace}/HEARTBEAT.md

；对于多heartbeat仓库，放在

{workspace}/heartbeats/{name}/HEARTBEAT.md

。

3. Test

3. 测试

Run one heartbeat to verify:

bash

murmur beat {workspace_path}

运行一次heartbeat进行验证：

bash

murmur beat {workspace_path}

Or for a named heartbeat:

对于命名heartbeat：

murmur beat {workspace_path} --name {name}


Show the user the outcome and output.

murmur beat {workspace_path} --name {name}


向用户展示测试结果和输出内容。

4. Evaluate

4. 评估

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.

询问用户：“这符合你的预期吗？”

不符合 → 根据反馈优化HEARTBEAT.md文件，再次测试。重复此过程直到用户满意。
符合 → 进入注册环节。

5. Register

5. 注册

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.
Verify registration:
```
murmur workspaces list
```
Schedule, timeout, model, and other settings live in the HEARTBEAT.md frontmatter — no need to edit config.json for these.
Only edit
```
~/.murmur/config.json
```
directly if you need a
```
permissions.deny
```
list (frontmatter only supports
```
permissions: skip
```
).
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
```
  )

将工作区注册到murmur，让守护进程识别到它：

运行
```
murmur init {absolute_workspace_path}
```
——这会自动将工作区注册到
```
~/.murmur/config.json
```
中（配置内容为
```
{ path, lastRun: null }
```
）。如果HEARTBEAT.md已存在，会跳过文件创建步骤但仍完成注册。
验证注册结果：
```
murmur workspaces list
```
计划、超时、模型和其他配置都存储在HEARTBEAT.md的前置块中——无需编辑config.json。
仅当需要设置
```
permissions.deny
```
列表时，才直接编辑
```
~/.murmur/config.json
```
（前置块仅支持
```
permissions: skip
```
）。
告知用户启动守护进程：
- ```
murmur start
```
  —— 前台运行并显示TUI（按
```
q
```
  退出，
```
d
```
  切换到后台）
- ```
murmur start --detach
```
  —— 后台运行（可通过
```
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).

最终的HEARTBEAT.md文件中不得留下
```
{placeholder}
```
占位符
在完成之前，必须使用
```
murmur beat
```
进行测试
必须让用户评估测试结果
如果heartbeat需要用户未安装的工具，告知用户需要安装的内容
一个heartbeat对应一个功能。同一仓库中的多个自动化任务——使用
```
heartbeats/
```
目录和
```
--name
```
参数。
计划建议：监控可用性使用
```
15m
```
，活跃开发工作使用
```
1h
```
，摘要/研究类任务使用
```
6h
```
–
```
1d
```
。当用户需要特定时间执行时，使用cron（例如
```
0 9 * * 1-5
```
表示工作日上午）。