claude-heartbeat

A background daemon that periodically wakes Claude Code using a HEARTBEAT.md checklist.

Inspired by OpenClaw's heartbeat mechanism and WakeClaude.

How it works

1. You define a HEARTBEAT.md checklist in your project root with items to monitor
2. You configure intervals, active hours, and optional scheduled tasks in heartbeat.config.json
3. The daemon periodically invokes claude CLI with your checklist as context
4. Claude checks each item and responds with HEARTBEAT_OK (all clear) or an alert

Quick start

# Install
npm install -g claude-heartbeat

# Initialize config files in your project
claude-heartbeat init

# Edit HEARTBEAT.md with your checklist
# Edit heartbeat.config.json with your preferences

# Start the daemon
claude-heartbeat start

# Or run a single heartbeat
claude-heartbeat run

Commands

| Command | Description | |---------|-------------| | start | Start the heartbeat daemon (background by default) | | start -f | Run in foreground mode | | stop | Stop the running daemon | | status | Show daemon status (PID, uptime) | | run | Run a single heartbeat immediately | | logs | View recent heartbeat logs | | logs -n 50 | View last 50 log entries | | init | Create example config files |

Configuration

heartbeat.config.json

{
  "interval": "30m",
  "model": "sonnet",
  "permissions": "plan",
  "heartbeatFile": "HEARTBEAT.md",
  "ackMaxChars": 300,
  "logRetention": 50,
  "activeHours": {
    "start": "09:00",
    "end": "22:00",
    "timezone": "America/Los_Angeles"
  },
  "schedules": [
    {
      "id": "nightly-review",
      "prompt": "Review the project for any issues and summarize.",
      "cron": "0 2 * * *",
      "model": "sonnet",
      "enabled": true
    }
  ]
}

| Field | Default | Description | |-------|---------|-------------| | interval | "30m" | Time between heartbeats ("15m", "1h", "2h30m") | | model | "sonnet" | Claude model to use | | permissions | "plan" | "plan" (read-only), "acceptEdits", or "bypassPermissions" | | heartbeatFile | "HEARTBEAT.md" | Path to checklist file | | ackMaxChars | 300 | Max chars for OK acknowledgments | | logRetention | 50 | Number of log entries to keep | | activeHours | none | Restrict heartbeats to a time window | | schedules | [] | Cron-scheduled one-off prompts |

HEARTBEAT.md

A markdown checklist that Claude reads each cycle. Keep it concise.

# Heartbeat Checklist

- [ ] Are tests passing?
- [ ] Any new error logs or warnings?
- [ ] Is the build succeeding?
- [ ] Any open issues that need attention?

Response protocol

• HEARTBEAT_OK: Claude starts its response with this token when everything is fine. The daemon logs it quietly.
• Alert: Any response without HEARTBEAT_OK is treated as an alert and surfaced in logs.
• Error: CLI failures, timeouts, or missing files are logged as errors.

Scheduled tasks

In addition to periodic heartbeats, you can schedule one-off prompts using cron expressions:

{
  "schedules": [
    {
      "id": "morning-standup",
      "prompt": "Summarize recent commits and open PRs for the daily standup.",
      "cron": "0 9 * * 1-5",
      "model": "sonnet"
    }
  ]
}

Logs

Logs are stored in .heartbeat/heartbeat.log.jsonl as JSON lines:

{"timestamp":"2026-02-10T10:30:00.000Z","type":"heartbeat","status":"ok","response":"All checks passing.","durationMs":4523}

View them with claude-heartbeat logs.

Prerequisites

• Claude Code CLI installed and authenticated
• Node.js 18+

License

MIT