coderClaw

Heartbeat (Gateway)

Heartbeat vs Cron? See Cron vs Heartbeat for guidance on when to use each.

Heartbeat runs periodic agent turns in the main session so the model can surface anything that needs attention without spamming you.

Troubleshooting: /automation/troubleshooting

Quick start (beginner)

  1. Leave heartbeats enabled (default is 30m, or 1h for Anthropic OAuth/setup-token) or set your own cadence.
  2. Create a tiny HEARTBEAT.md checklist in the agent workspace (optional but recommended).
  3. Decide where heartbeat messages should go (target: "last" is the default).
  4. Optional: enable heartbeat reasoning delivery for transparency.
  5. Optional: restrict heartbeats to active hours (local time).

Example config:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // optional: send separate `Reasoning:` message too
      },
    },
  },
}

Defaults

What the heartbeat prompt is for

The default prompt is intentionally broad:

If you want a heartbeat to do something very specific (e.g. “check Gmail PubSub stats” or “verify gateway health”), set agents.defaults.heartbeat.prompt (or agents.list[].heartbeat.prompt) to a custom body (sent verbatim).

Response contract

Outside heartbeats, stray HEARTBEAT_OK at the start/end of a message is stripped and logged; a message that is only HEARTBEAT_OK is dropped.

Config

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // default: 30m (0m disables)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
        target: "last", // last | none | <channel id> (core or plugin, e.g. "bluebubbles")
        to: "+15551234567", // optional channel-specific override
        accountId: "ops-bot", // optional multi-account channel id
        prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
        ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK
      },
    },
  },
}

Scope and precedence

Per-agent heartbeats

If any agents.list[] entry includes a heartbeat block, only those agents run heartbeats. The per-agent block merges on top of agents.defaults.heartbeat (so you can set shared defaults once and override per agent).

Example: two agents, only the second agent runs heartbeats.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.",
        },
      },
    ],
  },
}

Active hours example

Restrict heartbeats to business hours in a specific timezone:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
        },
      },
    },
  },
}

Outside this window (before 9am or after 10pm Eastern), heartbeats are skipped. The next scheduled tick inside the window will run normally.

Multi account example

Use accountId to target a specific account on multi-account channels like Telegram:

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // optional: route to a specific topic/thread
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

Field notes

Delivery behavior

Visibility controls

By default, HEARTBEAT_OK acknowledgments are suppressed while alert content is delivered. You can adjust this per channel or per account:

channels:
  defaults:
    heartbeat:
      showOk: false # Hide HEARTBEAT_OK (default)
      showAlerts: true # Show alert messages (default)
      useIndicator: true # Emit indicator events (default)
  telegram:
    heartbeat:
      showOk: true # Show OK acknowledgments on Telegram
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Suppress alert delivery for this account

Precedence: per-account → per-channel → channel defaults → built-in defaults.

What each flag does

If all three are false, CoderClaw skips the heartbeat run entirely (no model call).

Per-channel vs per-account examples

channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # all Slack accounts
    accounts:
      ops:
        heartbeat:
          showAlerts: false # suppress alerts for the ops account only
  telegram:
    heartbeat:
      showOk: true

Common patterns

Goal Config
Default behavior (silent OKs, alerts on) (no config needed)
Fully silent (no messages, no indicator) channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }
Indicator-only (no messages) channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }
OKs in one channel only channels.telegram.heartbeat: { showOk: true }

HEARTBEAT.md (optional)

If a HEARTBEAT.md file exists in the workspace, the default prompt tells the agent to read it. Think of it as your “heartbeat checklist”: small, stable, and safe to include every 30 minutes.

If HEARTBEAT.md exists but is effectively empty (only blank lines and markdown headers like # Heading), CoderClaw skips the heartbeat run to save API calls. If the file is missing, the heartbeat still runs and the model decides what to do.

Keep it tiny (short checklist or reminders) to avoid prompt bloat.

Example HEARTBEAT.md:

# Heartbeat checklist

- Quick scan: anything urgent in inboxes?
- If it’s daytime, do a lightweight check-in if nothing else is pending.
- If a task is blocked, write down _what is missing_ and ask Peter next time.

Can the agent update HEARTBEAT.md?

Yes — if you ask it to.

HEARTBEAT.md is just a normal file in the agent workspace, so you can tell the agent (in a normal chat) something like:

If you want this to happen proactively, you can also include an explicit line in your heartbeat prompt like: “If the checklist becomes stale, update HEARTBEAT.md with a better one.”

Safety note: don’t put secrets (API keys, phone numbers, private tokens) into HEARTBEAT.md — it becomes part of the prompt context.

Manual wake (on-demand)

You can enqueue a system event and trigger an immediate heartbeat with:

coderclaw system event --text "Check for urgent follow-ups" --mode now

If multiple agents have heartbeat configured, a manual wake runs each of those agent heartbeats immediately.

Use --mode next-heartbeat to wait for the next scheduled tick.

Reasoning delivery (optional)

By default, heartbeats deliver only the final “answer” payload.

If you want transparency, enable:

When enabled, heartbeats will also deliver a separate message prefixed Reasoning: (same shape as /reasoning on). This can be useful when the agent is managing multiple sessions/codexes and you want to see why it decided to ping you — but it can also leak more internal detail than you want. Prefer keeping it off in group chats.

Cost awareness

Heartbeats run full agent turns. Shorter intervals burn more tokens. Keep HEARTBEAT.md small and consider a cheaper model or target: "none" if you only want internal state updates.

This site is open source. Improve this page.