Introduction

In DeepSeek Harness (DSH), agents can typically wait for a command or task to complete, but some tasks are better suited for continuous monitoring: commands keep outputting, log files keep growing, and the agent needs to be woken up when a key new line appears.

dshworks/dsh-watch addresses this type of problem: it provides background stream listening for DSH agents, monitoring command output or new file lines, and waking up the agent via session-internal notifications that are filtered, batched, and byte-limited. The plugin also comes with an unattended daemon host to attach the watch to a long-term session.

What is it

dshworks/dsh-watch is a DSH plugin, package name @dshworks/dsh-watch, license MIT, requires Node >= 20.

Its core capabilities are:

  • Supports two stream sources: command and file
  • Monitors command output or new file lines
  • New lines arrive as notifications that are filtered, batched, and byte-limited
  • Supports optional JavaScript regex filtering
  • Each watch is a first-class background job (kind watch)
  • Can be used with job_list, job_output, job_kill
  • Supports wake budget/token bucket and event budget (max_events)
  • Supports autoArm profile configuration and the @dshworks/dsh-watch/daemon unattended host

Core Features

Two Stream Sources

The plugin supports monitoring two categories of sources:

  • command: listening to command output
  • file: listening to new file lines

The command source is started via shell capability and inherits the session’s sandbox policy and environment. File listening starts from the current end, does not deliver existing content; the file restarts from the beginning if truncated; non-existent files are continuously observed.

Filtering, Batching, and Byte Limits

New lines do not enter the session line-by-line without limits. The plugin supports optional JavaScript regex filtering, only matching lines enter notifications. Notifications themselves are also batched and byte-limited to control the volume of content entering the agent session.

The plugin also provides a set of configuration limits, including armed-watch cap per owner, notice byte limit, backlog budget, etc.

Management as Background Jobs

Each watch is a first-class background job, with kind set to watch. Therefore, standard DSH job management interfaces can be used:

  • job_list
  • job_output
  • job_kill

Installation and Usage

The installation command is as follows:

dsh plugin --profile web add @dshworks/dsh-watch

dsh plugin forwards to pnpm, so pnpm must be in PATH.

Typical Usage

Monitor Command Output

The following example monitors the output of npm run dev and only focuses on lines containing error, warn, or Ready:

watch(source: "command", command: "npm run dev", pattern: "error|warn|Ready", label: "dev")

Monitor New File Lines

The following example monitors new lines in a log file and only focuses on ERROR or FATAL:

watch(source: "file", path: "/var/log/app.log", pattern: "ERROR|FATAL")

Unattended Running

The plugin supports declaring standing watches with wakeRefillMs and autoArm in the profile config, and the @dshworks/dsh-watch/daemon can be used as an unattended host.

One available way to run is:

dsh plugin --profile watcher add @dshworks/dsh-watch
dsh --profile watcher | tee -a watcher.log

Use Cases and Notes

Suitable for scenarios where the agent needs to wake up when key information appears in command output or new file lines, such as development servers, logs, long-running scripts, etc.

Precautions before use:

  • The plugin runs with the current dsh process permissions; the command source is also started via shell capability and inherits the session’s sandbox policy and environment
  • Check the source code and MIT license before installation
  • Requires Node >= 20
  • dsh plugin forwards to pnpm, so pnpm must be in PATH
  • File listening starts from the current end, does not deliver existing content
  • There are configuration limits such as armed-watch cap per owner, notice byte limit, backlog budget, etc.

Links

Directory Page: https://www.skillhub.cn/plugins/dshworks/dsh-watch

GitHub: https://github.com/dshworks/dsh-watch