Preface

When building coding agents in DeepSeek Harness (DSH), a common situation is: the agent repeatedly reads code, edits files, runs commands, then encounters the same failure. At this point, checking official documentation, GitHub, or the web might be faster than continuing local trial-and-error.

dsh-research-nudge is an advisory research-debt guard designed for this scenario. It doesn’t directly execute searches or intercept tools; it simply injects a brief reminder into the next model step, prompting the agent to first assess whether external evidence is needed.

What This Is

dsh-research-nudge is a DSH plugin maintained by Leitarkkk, released under the MIT license. It observes the agent’s tool executions and, when reads, edits, executions, and repeated failures occur within a period without using recognized external research tools, it injects a brief reminder.

It does the following:

  • Converts the cumulative cost of the local loop into a deterministic score called Research Debt.
  • Injects a reminder into the next model step when state conditions are met.
  • Provides a model-visible research_nudge_snooze tool for agents to temporarily mute at the agent granularity.
  • Registers a research-nudge entry in the DSH configuration for easy override.

It does not:

  • Call LLMs.
  • Execute searches.
  • Block tool calls.
  • Force the agent to browse the web.

Core Features

Observing Local Trial-and-Error

The plugin focuses on agent signals in the local loop: reading code, editing files, executing commands, failing, and failing again. It accumulates these costs into Research Debt.

Injecting Reminders

When Research Debt or related state reaches thresholds set by the plugin, the plugin injects a brief reminder into the next model step. The reminder suggests the agent pause and assess: whether the current task can be completed with local evidence; if uncertain about APIs, errors, or platform behavior, whether it needs to check official documentation, GitHub, or the web.

After a reminder, a default 10-minute cooldown applies to prevent repeated reminders during that period.

Recognizing External Research

When the agent uses a recognized research tool, the cumulative state for that agent is reset. Research tools are matched by the researchTools rules in the plugin configuration.

Temporary Snooze

If the agent genuinely wants to proceed based on local evidence, it can call the research_nudge_snooze tool to temporarily suppress reminders. By default, this lasts 30 minutes and is capped by the maxAgentSnoozeMinutes limit.

Things to note:

  • Snoozing is per-agent; other agents are unaffected.
  • Research Debt continues to accumulate during snooze; it does not count as research and does not clear failure counters.
  • If the research_nudge_snooze call fails, it is logged as a normal failed call without resetting debt.

Installation and Enablement

First, ensure the environment meets the prerequisites:

DeepSeek Harness 0.1.0-rc.7
Node.js ^22.19.0 or >=24.0.0

Install from GitHub:

dsh plugin --profile web add github:Leitarkkk/dsh-research-nudge

If you want to pin a version, you can pin a tag or commit:

dsh plugin --profile web add github:Leitarkkk/dsh-research-nudge#<tag-or-commit>

If the package is published to npm, you can also use the prebuilt installation:

dsh plugin --profile web add dsh-research-nudge

Git installations run the prepare build in the package. pnpm may refuse the build until you explicitly trust it. It is recommended to review the source code and MIT license first, then follow DSH/pnpm prompts for build trust.

After installation, check the merged configuration layers and restart the profile:

dsh --profile web --dump-config
dsh web

Typical Usage

Overriding Plugin Configuration

The plugin registers a research-nudge entry in the DSH configuration. You can override this entry in the profile’s cordis.patch.yml:

- id: research-nudge
  config:
    enabled: true
    debtThreshold: <number>
    researchTools:
      - <research-tool-pattern>
    reminder: <custom-string>
    debug: false

The DSH patch layer replaces the entire config value for this entry rather than doing a deep merge, so it’s recommended to include all fields you want to preserve in the override.

Local Development Installation

If you want to modify or debug the plugin, clone and install locally:

git clone https://github.com/Leitarkkk/dsh-research-nudge.git
cd dsh-research-nudge
npm install
npm run check
dsh plugin --profile web add .

Using Temporary Snooze

In the agent’s tool-calling context, you can use the model-visible tool:

research_nudge_snooze

It suppresses reminders for a period, defaulting to 30 minutes, bounded by the maxAgentSnoozeMinutes limit.

Applicable Scenarios and Cautions

Scenarios where it fits:

  • Running coding agents in DSH’s web profile or other profiles.
  • Agents frequently performing local reads, edits, executions, and failed retries.
  • You want lightweight reminders to reduce repetitive trial-and-error without external evidence.
  • You accept the plugin works in an advisory capacity, without direct searches or tool interception.

Cautions before use:

  • The plugin runs as a DSH plugin using permissions available to the current dsh process; review the source code and license before installation.
  • The plugin is reminder-based, not mandatory search; reminders allow tasks that don’t need external research to proceed.
  • Configuration overrides replace the entire entry, not deep merge.
  • Temporary snooze only affects the calling agent and does not reset Research Debt.
  • The npm installation command assumes the package is published; if not published, prefer GitHub or local path installation.

Links

Plugin directory page:

https://www.skillhub.cn/plugins/Leitarkkk/dsh-research-nudge

GitHub repository:

https://github.com/Leitarkkk/dsh-research-nudge