Foreword

DeepSeek Harness (DSH) adopts a plugin-based architecture, allowing developers to extend its functionality. When managing multi-agent workflows, precisely tracking the lifecycle state of the root agent and sub-agents is critical. The lbryany/dsh-herdr plugin addresses this by aggregating the agent state inside a DSH process into the semantic state of a Herdr pane.

Plugin Introduction

Plugin name: lbryany/dsh-herdr
Maintainer: Lbryany
Functionality: DeepSeek Harness Herdr state integration.
Scope: The plugin runs inside the DSH TUI process and aggregates the root agent and sub-agents in that process into the semantic state of the current Herdr pane.

Core Features

State Mapping

The plugin maps DSH process states to Herdr states:

DSH process state Herdr state
Any agent has pending approvals blocked
No pending approvals, and any agent is running working
Agents exist, and all are idle idle
The last agent has been disposed or the plugin has been uninstalled release-agent

State Monitoring and Persistence

The plugin listens to the following events: agent/created, agent/status, agent/disposed, and session/event. It communicates with Herdr through a persistent NDJSON connection (HERDR_SOCKET_PATH), supports folding historical approval states during session recovery, and avoids losing pending approval information after restart.

State Reporting Mechanism

State reports are executed serially through an in-process queue and counted using epoch-microsecond seq. After restarting DSH in the same pane, the count does not restart from 1, ensuring that Herdr can correctly identify new reports.

Installation and Enablement

Before installation, ensure the environment meets the following requirements:
- DeepSeek Harness 0.1.0-rc.6
- Node.js 22.19+ or 24+
- A Herdr-managed pane (process environment includes HERDR_ENV=1 and HERDR_PANE_ID)

The installation command is as follows:

dsh plugin --profile tui add github:Lbryany/dsh-herdr

After installation, start the DSH TUI inside the Herdr pane.

Typical Usage

  1. Start the DSH TUI inside the Herdr pane.
  2. Run herdr agent list from another pane to view the status.
  3. Observe that DSH shows working while processing messages, blocked while waiting for tool approvals, and idle when finished, or done derived by Herdr based on visibility.

Design Details

  • Connection strategy: The plugin first attempts to establish a Unix domain socket or Windows named pipe connection through HERDR_SOCKET_PATH. If connection, timeout, or protocol failures occur, it automatically falls back to the Herdr CLI specified by HERDR_BIN_PATH.
  • Process reuse: The same DSH process reuses a single socket connection and does not start a Herdr child process for every state change.
  • Permissions: The plugin runs with the current dsh process permissions and is automatically disabled when not run inside a Herdr pane.

Applicable Scenarios and Notes

Suitable for developers who need to synchronize DSH agent states to a Herdr dashboard in real time. Before installation, review the source code and license (MIT).

References