DeepSeek Harness plugin development tutorial: end to end

A DSH plugin development tutorial runs through six steps: prepare the environment → create the plugin project → write apply → mount it with a cordis.yml patch → bundle it → install it into a profile and verify. The first three get the plugin running locally; the last three turn it into a package other people can install. The commands and expected output below follow the official docs in order, and every DeepSeek Harness plugin follows the same six-step path.

DSH plugin development step 1: prepare the environment

DSH plugin development needs a working run-from-source DeepSeek Harness, and the official tutorial starts from a repository checkout. With Node and pnpm in place, clone and install (Source):

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install

If the host itself is not set up yet, get Node versions and pnpm configuration right first via DSH plugin development environment - a version mismatch will manufacture fake failures at every later step.

DSH plugin development step 2: create the plugin project

Create a scratch directory inside the repository root to hold plugin source; tmp/ and scratch-* stay out of version control. The official tutorial does:

mkdir -p scratch-plugin/src

The name scratch-plugin is only an example. One rule actually matters: module paths resolve from the profile directory, so referencing source by absolute path from inside the checkout is the least painful option.

DSH plugin development step 3: write apply so the plugin can load

A DSH plugin at minimum is a TypeScript module that exports apply. Create scratch-plugin/src/my-plugin.ts:

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

export const name = 'hello-plugin'

export function apply(ctx: Context) {
  // Required dependencies are ready before apply runs.
  console.log('[hello-plugin] plugin loaded!')
}

name is the identity, apply is the entry point, and ctx is the channel through which you register capabilities. For the full rules on exports and naming see DSH plugin development spec.

DSH plugin development step 4: mount it with a cordis.yml patch

Use a --patch overlay to insert the local plugin into the config tree, then start the Web UI and watch the output. Three steps (Source):

1. Capture the absolute repository root - run pwd at the repository root. Expect: the absolute path, which the name field in the next step needs.

pwd

2. Write the overlay config - create scratch-plugin/cordis.yml and set name to the path printed above:

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

3. Start with the patch - run the command below. Expect: the Web UI comes up at http://127.0.0.1:3080 and the terminal prints [hello-plugin] plugin loaded! during startup:

pnpm dsh web --patch ./scratch-plugin/cordis.yml

Two things to remember: the plugin path must be absolute, and a patch file only contributes configuration - it does not change the profile directory from which the loader resolves module paths.

DSH plugin development step 5: bundle it

To let other people install it, package the plugin as a bundle. The layout:

hello-plugin/
├── package.json       # declares dsh.bundle
├── cordis.patch.yml   # the config layer this bundle contributes
└── index.js           # the plugin module referenced by the patch row

The four declarations in package.json:

{
  "name": "dsh-hello-plugin",
  "version": "0.1.0",
  "type": "module",
  "main": "index.js",
  "files": ["index.js", "cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

cordis.patch.yml references the package by name:

- insert:
  - id: hello
    name: dsh-hello-plugin

Note the difference: the development cordis.yml points at a source file by absolute path, while the published cordis.patch.yml uses the package name - after installation the package is resolvable from the profile's dependencies.

DSH plugin development step 6: install into a profile and verify

Run add, then --dump-config, then start - none of the three is optional. dsh plugin forwards its arguments to pnpm inside the profile directory (Source):

1. Install into the profile - run dsh plugin --profile demo add ./hello-plugin. Expect: the package lands in the profile dependencies; because it declares dsh.bundle, DeepSeek Harness appends it to dsh.profile.bundles.
2. Check the config layer - run dsh --profile demo --dump-config. Expect: your patch row appears in the printed config tree. Skipping this step makes it easy to misread "never mounted" as "the plugin has a bug".
3. Start and verify - run dsh --profile demo. Expect: the plugin takes effect in the running plugin tree and its output shows up in the terminal.

To see what finished community plugins look like, install one from DSH Plugin Hub and compare.

Once all six steps pass, these are the three places a DeepSeek Harness plugin tutorial gets stuck:

1. A relative plugin path - the name in step 4's cordis.yml must be absolute, or the loader resolves it from the profile directory and finds nothing.
2. A bundle missing cordis.patch.yml - if it is not in files, npm will not ship it, the installer gets no config layer, and the plugin installs without mounting.
3. Confusing local-directory installs with published packages - dsh plugin add ./hello-plugin installs from a local directory, which resolves differently from an npm package; see DSH plugin local directory install.

When the flow works end to end, submit the result for community listing via DSH plugin publishing. If a plugin installs but never activates, work backwards from the Fiber state in DSH plugin not taking effect.

Sources: official "Your first plugin", official Cordis tutorial, dsh CLI README