Preface

In DeepSeek Harness (DSH), agents are usually triggered by user messages. If you don’t ask, they generally won’t speak up. For long-running sessions waiting for external events, or sessions where the user leaves temporarily, this pattern makes it easy to miss progress, risks, and bottlenecks.

The dsh-plugin-heartbeat introduced below is a DSH plugin used to add a scheduled wake-up mechanism to agents. It allows agents to proactively speak up in idle moments or between tasks at a set rhythm: report progress if there is any, report risks if there are any, or provide a brief explanation if there is no content.

What is it

Maintained by LittleBlackTong, dsh-plugin-heartbeat is released under the MIT license. It is a Host-plane Cordis plugin that listens for the agent/created event and attaches an independent timer to each root agent.

It injects a synthetic user message via agent.followup(), with the message source marked as source.kind === 'plugin'. This mechanism is used to make the agent proactively report its status rather than initiating new tasks on its own.

Core Capabilities

Scheduled Wake-up

The plugin wakes up the agent according to a set cycle. If the agent is idle, it immediately starts a new round; if the agent is busy, the message enters a queue to be processed after the current round ends. If it remains busy continuously, only one pending message is retained in the queue; no accumulation occurs.

Backoff and Hard Stop

Heartbeat intervals support backoff: the initial interval is 10 minutes; if no human replies, subsequent intervals increase according to [base, 2×base, 3×base].

When consecutive beats fail to receive a human reply for pauseAfterMissed times, the plugin will hard stop the timer. The heartbeat revives after the user’s next message arrives.

Pre-Delivery Compression

Supports compactBeforeBeat. When enabled, the plugin compresses history into checkpoint summaries before delivering a heartbeat, reducing the amount of context injected per beat.

Frequency Control and Display

Supports maxBeatsPerHour, setting an upper limit on heartbeats for a 60-minute window.

Injected heartbeat messages are rendered as collapsed context rows in the conversation stream, not as a full user bubble.

Installation and Activation

The installation command is as follows:

dsh plugin --profile <profile> add dsh-plugin-heartbeat

Restart DSH after installation for the changes to take effect. Plugin runtime dependencies:

@deepseek-ai/cordis ^4.0.1
@deepseek-ai/schemastery ^3.18.1
Node >=18

The plugin runs with the permissions of the current DSH process. It is recommended to check the source code and MIT license before installation to decide whether to add it to your own profile.

Runtime configuration is handled via <dshHome>/heartbeat.json. If overriding a composition key, such as prompt, use the entry ID without insert to override.

Do not manually write the following into your profile’s cordis.patch.yml:

- insert:
    id: dsh-heartbeat

This may result in duplicate loader entry id "dsh-heartbeat", leading to startup failure.

Typical Usage

After installing and restarting DSH, you can go to Settings → Heartbeat panel to adjust frequency, toggle switches, and pause thresholds. Changes are applied immediately upon saving without needing a restart.

If you only want to change the default prompt, you can override prompt using composition. An example is as follows:

- id: dsh-heartbeat
  config:
    prompt: |
      当前时间 {{time}}。
      汇报进展、风险或卡点；没有内容就简短说明。
      总长不超过 5 句。

The {{time}} above will be replaced with the current time. This example only uses confirmed template variables and the limit of no more than 5 sentences.

Usage Boundaries

Please pay attention to the following points when using:

  • Heartbeats only exist while the DSH process is alive; they stop when the DSH application is closed.
  • Each session (root agent) has its own timer; child agents do not have a heartbeat.
  • Heartbeats do not interrupt ongoing tasks; they will add a sentence after the task ends.
  • The default prompt instructs the agent not to take the initiative to start new work on its own; the purpose of the heartbeat is to report, not to start new tasks.
  • A heartbeat that was already queued before the hard stop will be consumed when the current round ends; no new beats will be generated thereafter.
  • Zero dependency on dsh-plugin-memory; when installed simultaneously, both messages queue in the same inbox.
  • The plugin host needs to build a GET/POST /api/heartbeat/config route, and the settings panel connects directly to this route.

Conclusion

The value of dsh-plugin-heartbeat is simple: turning “user asks, agent answers” into “agent speaks up proactively when the conversation is stale”. It is suitable for DSH users and developers who need long-running agents and wish to receive status updates.

Community Directory Page:
https://www.skillhub.cn/plugins/LittleBlackTong/dsh-plugin-heartbeat

GitHub Repository:
https://github.com/LittleBlackTong/dsh-plugin-heartbeat