Manage Session Heartbeats for Active Work

A session heartbeat is a recurring prompt attached to one live Hermes session. It is useful when an ongoing conversation needs periodic attention while the session remains open—for example, checking whether a long task has changed state or prompting the agent to review its current work.

A heartbeat is deliberately different from cron. Cron is the durable choice for work that must run independently on a schedule. A heartbeat belongs to the current session and follows that session's lifecycle.

Choose heartbeat or cron

Use a heartbeat when:

• the recurring turn should retain the current conversation context;
• one active session owns the work;
• a missed interval should not create a backlog; and
• it is acceptable for the pulse to stop when the owning process is not active.

Use cron when:

• the task must survive a closed terminal or inactive chat;
• delivery needs a specific channel or destination;
• the work has an independent schedule and history; or
• a deterministic script can run without an LLM.

Understand the timing model

Hermes supports one heartbeat per session. Setting another replaces the current one. The minimum interval is 60 seconds.

Heartbeats are idle-only: they do not interrupt a running turn. If the session is busy when a tick becomes due, Hermes waits until the next idle poll. Multiple missed ticks coalesce into one heartbeat turn rather than replaying a queue of stale checks. A waiting user message takes priority.

/heartbeat every 10m Review the current task state and report only a material change.
/heartbeat status

The command text should be narrow. A vague prompt such as “keep working” can produce repetitive turns without a clear completion test.

Heartbeat setup checklist

• Confirm the work belongs to one live session.
• Choose an interval of at least 60 seconds.
• Define the exact state or change to inspect.
• Ask for silence or a short status when nothing changed.
• Check /heartbeat status after configuration.
• Clear or replace the heartbeat when the task changes.

Common pitfalls

Treating a heartbeat as a daemon

A heartbeat does not create an independent worker. If the owning process was not running, missed intervals do not execute later as a backlog.

Polling too frequently

A short interval can waste model turns and crowd out useful work. Match the interval to how quickly the underlying state can actually change.

Hiding the completion condition

The prompt should say what counts as progress, failure, or completion. Otherwise the agent may keep producing observational updates after the useful work is done.

Verification steps

1. Run /heartbeat status and confirm the prompt and next-fire interval.
2. Leave the session idle for one interval.
3. Confirm exactly one heartbeat turn appears.
4. Send a normal user message near a due tick and confirm the user message wins.
5. Clear or replace the heartbeat, then confirm the status changed.

Official reference

See the official Session Heartbeats documentation for current commands and lifecycle details.