Introduction

DeepSeek Harness (DSH) adopts a plugin-based architecture. When developing multi-agent workflows, relying solely on a single primary agent often makes it difficult to achieve independent review, fact-checking, or parallel cognitive processing. dsh-shadow-mind is a DSH plugin ported from pi-shadow-mind, and it implements parallel cognitive capabilities in the DSH runtime.

The plugin activates configured “shadow agents” randomly via a heartbeat scheduler after each turn of the primary agent. These shadow agents have independent responsibilities, tool permissions, and execution timeouts, and can provide independent perspectives and auxiliary work while the primary agent processes tasks.

Core Features

The plugin currently includes the following implemented core capabilities:

  • Heartbeat scheduling: After each turn of the primary agent, randomly activates enabled shadow agents according to the configured probability.
  • Restricted-tool shadows: Shadow agents receive only the cleaned main session trajectory and an explicit tool whitelist. The default whitelist is read-only; other tools can be configured to expand access.
  • Single-run timeout: Each shadow run is limited by timeout_seconds (or a configured default value); timed-out runs are interrupted and release their slot.
  • Lifecycle cleanup: Completed shadow runs are removed through the subagent/end event, ensuring the active count remains accurate.
  • Management tools: Create, update, delete, list, enable, or disable shadow definitions through model tools.
  • Configuration tools: Read and write global configuration through model tools; merged results are validated before writing.
  • Pause/resume/epoch: Supports /shadow pause and /shadow resume commands. Pausing terminates running shadows; new user input increments the epoch and cancels runs from the previous epoch.
  • Automatic switching: Controls heartbeat activation with /shadow auto on|off commands.
  • Tool call parameter sanitization: Sanitizes tool call parameters before forwarding them to shadow agents, preventing credential leakage.

Installation and Enabling

DSH plugins are loaded through Cordis composition (configuration files or agent presets). The installation steps are as follows:

  1. Install the package into the specified DSH profile with the following command:
dsh plugin --profile web add @winterchenhuan/dsh-shadow-mind@latest
  1. Restart the DSH service, and the plugin will be loaded.

For local development, build the package first:

cd /path/to/dsh-shadow-mind
npm install
npm run build
dsh plugin --profile web add /path/to/dsh-shadow-mind

Configuration

Global configuration is stored in the shadow-mind: section of ~/.dsh/settings.yaml. Shadow definition files are located in the ~/.dsh/agent/shadow-minds/ directory.

Global Configuration Example

shadow-mind:
  heartbeatProbability: 0.33
  maxParallelShadows: 2
  defaultShadowTimeoutSeconds: 120
  defaultThinkingLevel: low

Main configuration items include:
* heartbeatProbability: Probability of activating shadows per turn (0 to 1).
* maxParallelShadows: Maximum number of shadows allowed to run concurrently.
* defaultShadowTimeoutSeconds: Default seconds used when a timeout is not set in the definition.

Shadow Definition Example

---
id: grounded-reviewer
name: Project Grounding Checker
enabled: true
activation_probability: 0.6
run_with_model: openai/gpt-5-mini
thinking_level: low
tools:
  - read
  - grep
  - glob
---

检查主代理的声明是否得到当前工作区的支持。如果没有值得报告的内容，回复：NOT_RELEVANT。

Usage

After installing and restarting DSH, start the service through the Web interface:

dsh web

Common Commands

The plugin provides a unified control interface via /shadow commands:

  • /shadow status: View the current state (activated/paused, automatic mode, epoch, number of runs, etc.) and configuration diagnostics.
  • /shadow list: List defined shadows.
  • /shadow probe <id> [tools]: Manually run the specified shadow (without waiting for a heartbeat), optionally specifying a tool list.
  • /shadow auto on|off: Enable or disable automatic heartbeat activation.
  • /shadow pause: Pause all shadow runs.
  • /shadow resume: Resume shadow runs.

Workflow

  1. Use /shadow status to confirm that the plugin is loaded.
  2. Use /shadow list to view available shadow definitions.
  3. Use /shadow probe grounded-reviewer to manually test whether a shadow works correctly.
  4. In the primary agent conversation, as long as automatic mode is enabled, shadows will be activated automatically after primary agent turns with the configured probability.

Notes

  • Current status: This is a functional prototype. Core heartbeat scheduling, restricted tools, timeouts, lifecycle cleanup, and management tools have all been verified to work.
  • Write permissions: Persistent writes are controlled by the DSH approval service; when that service is mounted, operations require user approval.
  • Security mechanisms: Tool call parameters are sanitized before being forwarded to shadows; tool results are summarized.
  • License: The plugin uses the MIT License. As a plugin, it runs with the permissions of the current DSH process; review the source code and license before installation.

The plugin is a practical component in the DSH ecosystem for implementing multi-agent parallel cognition, suitable for scenarios that require adding independent review or computational capabilities alongside the primary agent. For related documentation and source code, refer to DeepSeek Harness Ecosystem Catalog or GitHub Repository.