heartbeat-cron

Heartbeat Creator

構造化されたインタビュー、テスト実行、改善ループを通じて、murmur 用のよく練られた HEARTBEAT.md ファイルを作成します。

コンテキスト

Murmur は最小限のスケジューラーです。HEARTBEAT.md ファイルを読み取り、その内容をスケジュールに従って Claude に送信し、応答を分類します:

• HEARTBEAT_OK — 報告事項なし(サイレント)
• ATTENTION: ... — 人間の注意が必要(ログに記録 + TUI で表示)

Murmur はユーザーに通知できません。 プロンプトを実行して結果をログに記録するだけです。ユーザーが通知(Slack、Telegram、プッシュ)を希望する場合、HEARTBEAT.md 自体に配信ステップを含める必要があります。ハートビートがパイプライン全体です: データ収集 → 判断 → 実行 → 配信。

各ハートビートはステートレスです。 毎回の実行は、以前の実行の記憶がない新しい Claude セッションです。時間経過に伴う変化(価格差、最終確認タイムスタンプ)を追跡する必要があるワークフローでは、ワークスペース内のファイルを簡易的な状態ストアとして使用してください(例: last-price.txt、tracking-state.json)。

スリープ/ウェイクの動作。 マシンがスリープすると、デーモンはフリーズし、ティックは発火しません。ウェイク時には、期限切れのジョブが即座に実行されますが、複数回の未実行は 1 回のキャッチアップ実行にまとめられます(未実行の間隔ごとに 1 回ではありません)。これはハートビート形式のタスクにとって正しい動作です。過去のチェックを再生するのではなく、現在の状態を確認したいからです。ユーザーが信頼性の高いスケジューリングを必要とする場合は、マシンのスリープを無効にすることを勧めてください(README の FAQ を参照)。

HEARTBEAT.md のフォーマット

すべてのハートビートは、オプションの YAML frontmatter ブロックを持つ Markdown ファイルです。Frontmatter の値は config.json より優先されます。

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

注意:

• interval または cron — どちらか一方を使用し、両方は使用しないでください。インターバル: 15m、1h、6h、1d。Cron: 標準の 5 フィールド式。
• permissions: "skip" は、frontmatter でサポートされる唯一の permissions 値です。拒否リストには config.json を使用してください。
• murmur init は、これらのフィールドが事前に入力されたテンプレートを生成します。

ワークフロー

0. プリフライト

開始する前に、murmur がインストールされていることを確認します:

which murmur

• 見つかった → インタビューに進みます。
• 見つからない → Homebrew 経由でインストールします:

  brew install t0dorakis/murmur/murmur
  

  Homebrew が利用できない場合は、ソースからインストールします:

  git clone https://github.com/t0dorakis/murmur.git
  cd murmur && bun install && bun run build
  # Then add ./murmur to PATH
  

フラグを使用してワークスペースをすぐにスキャフォールドすることもできます:

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

リポジトリごとに複数のハートビート — --name を使用して、heartbeats/ ディレクトリにハートビートを作成します:

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

これにより、ワークスペース内に heartbeats/<name>/HEARTBEAT.md が作成されます。すべてのハートビートはリポジトリルートを CWD として共有します。ルートの HEARTBEAT.md も、名前付きハートビートと併用して引き続き機能します。

1. ヒアリング

AskUserQuestion を使って集中的にヒアリングします。一度に 1 ～ 2 個の質問を行い、以前の回答に基づいて進めます。

ラウンド 1 — ゴール:

何を自動化したいのかを尋ねます。まだ決まっていない、あるいは模索中であれば、references/examples.md を読んで、コード/リポジトリ、調査/インテリジェンス、運用/インフラ、個人/クリエイティブといったカテゴリからヒントを得てください。ユーザーの状況に合った例を提案します。

ラウンド 1b — ツールの調査:

詳細に入る前に、ユーザーのゴールに、すでにインストールされているもの以外のツールが必要かどうかを確認します。ウェブ検索を実行して、役立ちそうな CLI、MCP サーバー、エージェントスキルを探してください。

ブラウザーツール — 価値のあるハートビートの多くは、実際のウェブサイトとのやり取りを必要とします（価格の確認、ページの監視、ポータルへのログインなど）。Claude の組み込み WebFetch は単純な静的ページには使えますが、JavaScript レンダリング、ログインフロー、アンチボット対策を備えたサイトには本物のブラウザーが必要です:

• agent-browser — AI エージェント向けのヘッドレスブラウザー CLI。Claude Code ですぐに使えます。
• pi-browser — pi 向けのブラウザー拡張。agent: pi と組み合わせて使用します。

その他のツール — ウェブで "{ユーザーのゴール}" CLI tool または "{ユーザーのゴール}" MCP server を検索するか、コミュニティスキルについては skills.sh を確認してください。例:

• カレンダーへのアクセス → Google Calendar MCP または pi-google-calendar 拡張
• Slack/Discord への配信 → skills.sh の webhook スキル
• GitHub の操作 → gh CLI がインストールされていることを確認してください

見つけた内容をユーザーに伝え、ハートビートをより高機能にするためにインストールすべきものを提案してください。

ラウンド 2 — 詳細:

ユーザーのゴールに基づいて、具体的な内容を掘り下げます:

• どのツール/API/コマンドが必要ですか？（gh、curl、特定の URL、API キー）
• ワークスペースディレクトリはどこですか？
• どのくらいの頻度で実行しますか？2 つの選択肢があります:
  • インターバル — 固定の頻度: 15m、1h、6h、1d
  • Cron — 正確なスケジュール: 0 9 * * 1-5（平日午前 9 時）、*/30 * * * *（30 分ごと）
  • cron を選んだ場合は、タイムゾーンを確認してください（デフォルトはシステムのローカル tz）
• ハートビートにデフォルトの 5 分のタイムアウト以上の時間が必要ですか？（例: 長時間実行タスクには timeout: 15m）
• モデルの希望はありますか？（デフォルトではエージェントのデフォルトが使用されます。model: opus、model: sonnet などを設定できます）
• エージェントの選択: claude-code（デフォルト）は Claude Code CLI を実行します。codex は OpenAI Codex CLI を実行します（サンドボックスポリシーを使用）。pi は pi エージェントを実行します（ブラウザー拡張を備えています）

ラウンド 3 — 配信:

これは重要です。結果をどのように受け取りたいかを尋ねます。選択肢:

• ワークスペース内のファイルに書き込む（最もシンプル — 良いデフォルトです）
• webhook 経由で Slack/Discord に投稿する
• Telegram ボット API 経由で送信する
• GitHub の issue/コメントを作成する
• ntfy.sh 経由でプッシュ通知する
• ATTENTION レスポンスを使うだけ（ユーザーが TUI/ログを確認します）

伝えておきましょう: murmur は単なるスケジューラーであり、何も転送しません。通知を受け取りたいなら、ハートビート自体が通知を行う必要があります。

ラウンド 3b — 認証情報（必要な場合）:

配信やデータソースにトークン/webhook が必要な場合:

• ワークスペース内の .env の環境変数が利用できます（Bun が自動的に読み込みます）
• 機密性の高い値は .env に入れ、ハートビート内で $VAR_NAME として参照してください

2. ドラフト

HEARTBEAT.md ファイルを作成します。ルール:

• 少なくともスケジュール (interval または cron) を含む YAML フロントマターブロックを含めてください。インタビューに基づいて、必要に応じて timeout、model、その他のフィールドを追加してください。
• HEARTBEAT_OK / ATTENTION に関する指示は含めないでください — これらはランタイムが自動的に注入します
• すべてのステップを明示的に記述してください — Claude はハートビート間で記憶を持ちません
• 変更検出ワークフロー (価格の下落、新着アイテム、ステータス変更) では、ワークスペース内の状態ファイル (例: last-price.txt、tracking-state.json) を読み書きするステップを含めてください
• 実際の値を含む正確なコマンドを含めてください ({placeholder} を残さないでください)
• ユーザーが通知を希望する場合は、配信ステップを含めてください
• 焦点を絞ってください — 1 つのハートビートにつき 1 つの目的
• シークレットには $VAR_NAME を使用してください

ファイルは、単一ハートビートのワークスペースでは {workspace}/HEARTBEAT.md に、複数ハートビートのリポジトリでは {workspace}/heartbeats/{name}/HEARTBEAT.md に配置してください。

3. テスト

1 回ハートビートを実行して検証します:

murmur beat {workspace_path}
# Or for a named heartbeat:
murmur beat {workspace_path} --name {name}

ユーザーに結果と出力を表示します。

4. 評価

ユーザーに尋ねます: 「期待どおりに動作しましたか?」

• いいえ → フィードバックに基づいて HEARTBEAT.md を改善し、再度テストします。満足するまで繰り返します。
• はい → 登録に進みます。

5. 登録

デーモンが認識できるように、ワークスペースを murmur に登録します:

1. murmur init {absolute_workspace_path} を実行します — これによりワークスペースが ~/.murmur/config.json に自動登録されます ({ path, lastRun: null } として)。HEARTBEAT.md がすでに存在する場合、作成はスキップされますが、登録は行われます。
2. 登録を確認します: murmur workspaces list
3. スケジュール、タイムアウト、モデル、その他の設定は HEARTBEAT.md のフロントマターにあります — これらについて config.json を編集する必要はありません。
4. permissions.deny リストが必要な場合にのみ、~/.murmur/config.json を直接編集してください (フロントマターは permissions: skip のみをサポートします)。
5. ユーザーにデーモンの起動を伝えます:
   • murmur start — TUI 付きのフォアグラウンド (q で終了、d でデタッチ)
   • murmur start --detach — バックグラウンドモード (murmur watch で再アタッチ)

ルール

• 最終的な HEARTBEAT.md に {placeholder} の値を絶対に残さないでください
• 完了を宣言する前に、必ず murmur beat でテストしてください
• 必ずユーザーにテスト結果の評価を依頼してください
• ハートビートがユーザーのインストールしていないツールを必要とする場合は、何をインストールすべきかを伝えてください
• 1 つのハートビート = 1 つの目的。同じリポジトリで複数の自動化を行う場合は、--name を指定して heartbeats/ ディレクトリを使用してください。
• スケジュールの提案: 稼働監視には 15m、活発な開発作業には 1h、ダイジェスト/調査には 6h〜1d。ユーザーが特定の時刻を希望する場合は cron を使用してください (例: 平日の朝なら 0 9 * * 1-5)。