DeepSeek Harness plugin environment: Node, pnpm, deps

A DeepSeek Harness plugin development environment needs only three things: Node.js, pnpm, and a runnable copy of Harness. The official prerequisite is "start from a repository checkout that has completed the run-from-source path," so the first step is not writing code — it is getting pnpm dsh web to run. Every DSH plugin needs the same three things.

DSH plugin development environment checklist: three things

The official prerequisite for plugin development is one sentence: start from a repository checkout that has completed the run-from-source path. Unpacked, that is three things (source):

Watch the Node version: the create-dsh-plugin scaffolder declares Node ^22.19.0 || >=24.0.0 in its engines field — an older runtime fails during install (source).

Two ways to get DeepSeek Harness for DSH plugin work

Use npx if you only want to run Harness; use a source checkout to write plugins — because local debugging depends on the checkout directory. The official README offers both (source):

1. Run the published build (for users): npx @deepseek-ai/dsh web, which you should expect to start the Web UI in one command.
2. Use a source checkout (recommended for plugin work): git clone https://github.com/deepseek-ai/deepseek-harness.git, then cd deepseek-harness, pnpm install, pnpm run build, and finally pnpm dsh web, which you should expect to start the same Web UI from your own checkout.

Why option 2 for plugin work: the official plugin tutorial creates a scratch-plugin directory from the repository root and mounts the plugin's absolute path through a --patch overlay — plugin paths are resolved from the profile directory, so referencing local files is simplest inside the checkout. The two options coexist: npx for daily use, the checkout for plugin work. For a step-by-step breakdown of the source build, see building from source.

Creating a DSH plugin project: scaffold or hand-write

Use the scaffolder to start fast, or hand-write a single file to understand the mechanics. create-dsh-plugin offers tool / events / webui templates, includes a --verify smoke test, and pins versions with the next tag (source):

1. Scaffold a project: npx create-dsh-plugin my-plugin -t tool, which you should expect to generate package.json, tsconfig, and template code.
2. Or hand-write the minimal project, which is one file — create scratch-plugin/src/my-plugin.ts at the checkout root:

import type { Context } from '@deepseek-ai/cordis'

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  console.log('[hello-plugin] plugin loaded!')
}

The only difference is startup speed: the scaffolder brings package.json, tsconfig, and template code, while hand-writing means adding package.json yourself (needed for packaging). For the full walkthrough, see the development tutorial.

Which three dependencies a DSH plugin installs

Dependencies are on demand — a minimal plugin needs only types. The three official packages and their jobs:

Do not install everything blindly: the type package (cordis) is usually a dev dependency, while what the plugin actually needs at runtime is a package used by apply, such as dsh-tools (source).

DSH plugin environment check: getting this far is enough

The environment is fine not when things are installed, but when a minimal plugin loads. Run pwd at the checkout root for the absolute path and write scratch-plugin/cordis.yml:

1. Get the absolute path: run pwd at the checkout root, which you should expect to print the path you put in the overlay below.
2. Write the overlay at scratch-plugin/cordis.yml:

- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

3. Start Harness with the overlay: pnpm dsh web --patch ./scratch-plugin/cordis.yml, which you should expect to print [hello-plugin] plugin loaded!.

Printing [hello-plugin] plugin loaded! means the environment passes. If nothing prints, check in this order: is the path absolute → did pnpm install finish → does the Node version satisfy engines → did the checkout run pnpm run build. Those four cover the vast majority of environment problems.

After the DSH plugin environment is ready

Once the environment passes, decide the plugin's form and capability placement before writing code. Suggested order: use the development guide to choose function / object / class and where capabilities go, follow how to write a plugin to write it, then run the development spec checklist. For distribution, see packaging into a bundle and publishing to the plugin hub.