dsh-subagent

August 28, 2026 · View on GitHub

English | 中文

dsh-subagent is a community DeepSeek Harness plugin that turns named subagent profiles into model-visible delegation tools. Each profile fixes a backend, a model route, and a reasoning policy, and exposes one tool named subagent_<profile> to every live root Agent.

This repository is independent of the core @deepseek-ai/dsh-subagent package. The core package provides the ctx.subagents service; this plugin composes that service into configurable tools such as subagent_fast and subagent_reviewer, plus the custom_subagent management tool.

Features
Prerequisites
Install
Where state lives
Usage tutorial
Configuration format
Update and uninstall
Troubleshooting
Model experience
Known limitations and deferred work
Development
License

Features

Create, edit, and delete named subagent profiles from Settings → Subagents.
Choose spawn for an independent child context or fork to inherit the completed parent conversation.
Follow the current conversation's Provider and Model, or pin a custom Provider/Model route.
Follow the conversation's reasoning effort, use the selected model's default, or pin a custom effort.
Refresh custom Provider, Model, and effort choices from the live Host model catalog.
Apply profile updates without restarting the Host; existing continuable children retain the route resolved when they were created.
Manage the same durable profiles through the model-visible custom_subagent tool.
Mark one profile as the default subagent: a selector at the top of the settings page or the custom_subagent set-default action. While set, every root Agent's system prompt gains one short section that nudges unnamed delegation requests toward the matching subagent_<name> tool.

Prerequisites

Requirement	Version / detail	How to check
DeepSeek Harness	`0.1.1-rc.2` compatible packages (this plugin's peerDeps pin `0.1.1-rc.2`)	`dsh --version`
DSH profile	The profile you want to extend must be `web` (or another profile that loads the Web UI). `headless` and `tui` profiles do not surface the settings page.	`dsh profile list`
Node.js	`^22.19.0` or `>=24.0.0`	`node -v`
pnpm	On `PATH`; the CLI delegates installs to pnpm	`pnpm -v`
Base composition	A profile that ships `spawn` and `fork` subagent providers and the model catalog. The shipped `web` and `headless` profiles do; custom profiles must include `@deepseek-ai/dsh-subagent-spawn` and `@deepseek-ai/dsh-subagent-fork` (or equivalent providers) plus the `dsh-tool-subagent` capability.	`dsh plugin --profile web why` (look for `dsh-tool-subagent`, `dsh-subagent-spawn`, `dsh-subagent-fork`)
Network	HTTPS to `github.com` and `registry.npmjs.org` for the GitHub install path	`curl -fsI https://github.com`

If any check fails, fix it before installing the plugin. The CLI does not auto-install missing prerequisites.

Install

Choose an install path

Path	When to use	Builds required?
GitHub (recommended for users)	You want a reproducible install of a published version. Pin to a commit SHA in production.	No (the repo ships executable JavaScript).
Local checkout	You are developing or debugging the plugin and want changes picked up after restart.	`pnpm install` once.
npm registry	When (and if) a future release is published to npm.	No.

Path A — Install from GitHub

Install the plugin into the Web profile:

dsh plugin --profile web add github:xie-tj/dsh-subagent

For reproducible installations, pin a commit:

dsh plugin --profile web add github:xie-tj/dsh-subagent#09402ca21e086bed604f86818624a7435d65b572

(09402ca2 is the current published commit on main; replace it with the SHA you want to lock to.)

The CLI initializes the profile directory if it is missing, then delegates the rest to pnpm. Relative path specs (e.g. add . from a plugin checkout) are anchored to your current working directory, not the profile.

Verify the install:

dsh plugin --profile web why | grep -i dsh-subagent

You should see the plugin name, version, and its declared cordis.patch.yml layer in the dependency tree.

Path B — Install from a local checkout

git clone https://github.com/xie-tj/dsh-subagent.git
cd dsh-subagent
pnpm install
dsh plugin --profile web add .

pnpm install resolves the plugin's own devDependencies (loader and include helpers, dsh-scope). The CLI then registers the directory as a local dependency in the Web profile. Edits inside dsh-subagent/ take effect after restarting the Web profile.

Start or restart the Web profile

dsh --profile web

Open http://127.0.0.1:3080 (or the URL printed by the CLI), then go to Settings → Subagents. The initial profiles are listed in the Usage tutorial below.

Install into a non-`web` profile

The plugin declares dsh.client.platform: web. The settings UI and the subagent_<name> tools require a profile that loads the Web runtime. To install into a different profile, add it the same way:

dsh plugin --profile <name> add github:xie-tj/dsh-subagent

…but the profile must additionally load @deepseek-ai/dsh-client-ui-settings (or the settings UI consumer you want) for Settings → Subagents to render. The custom_subagent management tool is always available to the Agent regardless of UI.

Where state lives

The plugin keeps no on-disk state of its own. Three locations matter:

DSH settings provider — the Web profile's settings file. It contains a dsh-subagent namespace with profiles and the optional defaultProfile. The Settings page and the custom_subagent tool both write here. Find the file with dsh plugin --profile web why (look for the settings entry) or the DSH_HOME / $DSH_HOME environment variable.
Profile dependency manifest — the Web profile's package.json lists the plugin under dependencies. The CLI reconciles this with the actual install state on every add / remove / update. To audit: dsh plugin --profile web why.
Composition layer — the plugin's cordis.patch.yml is merged into the profile's Cordis composition by the CLI's bundle reconciler. Inspecting it requires reading the profile's resolved cordis.yml; the easiest way is dsh plugin --profile web why | grep -A2 'dsh-subagent'.

The plugin does not read the retired $DSH_HOME/custom-subagents.json file. Flat provider, model, and reasoningEffort fields belong to an obsolete pre-release format and are rejected at load.

Usage tutorial

1. Open the Subagents settings page

Open Settings → Subagents. The initial profiles are:

Profile	Backend	Model route	Reasoning	Child context
`fast`	`spawn`	Follow conversation	Custom `low`	Independent context
`reviewer`	`fork`	Follow conversation	Custom `high`	Inherits the completed parent conversation

These are editable user profiles supplied as initial plugin settings, not read-only DSH system profiles.

2. Configure a profile

Select Edit on a profile and choose:

Backend — spawn or fork.
Model configuration — follow the current conversation or select a custom Provider and Model.
Reasoning configuration — follow the conversation/model default or select a custom effort.
Description — explains the profile's intended work to the model.

Custom routing always stores Provider and Model together. If the selected route disappears from the live model catalog, the UI shows the stale value and blocks saving until a valid route is selected.

3. Create a specialized profile

Select New subagent, enter a lower-case identifier such as deep-research, and configure its backend and policies. Profile names must match:

^[a-z][a-z0-9_-]{0,23}$

The profile immediately creates a tool named subagent_deep-research for each live root Agent.

4. Set the default subagent

Pick a profile in the Default subagent selector at the top of the page, or call the custom_subagent set-default action (omitting name clears the designation). While set, each root Agent's system prompt gains one short section: delegation requests that name no profile — such as "open a subagent" — prefer the matching subagent_<name> tool.

A defaultProfile that names no existing profile is rejected at load and at save time. The current default profile cannot be deleted until another default is chosen or the designation is cleared.

5. Use a profile in a conversation

Ask the Agent to delegate work to the named profile, for example:

Use the reviewer subagent to inspect this change for correctness and test gaps.

The Agent can call subagent_reviewer; routing choices are fixed by the saved profile and are not exposed as tool-call arguments.

Configuration format

The Settings page and custom_subagent tool write the same dsh-subagent settings namespace. A representative settings.yaml section is:

dsh-subagent:
  defaultProfile: fast
  profiles:
    - name: fast
      description: Quick lookups and lightweight checks.
      backend: spawn
      modelRouting:
        mode: follow-conversation
      reasoning:
        mode: custom
        effort: low
    - name: reviewer
      description: Review changes with a dedicated model.
      backend: fork
      modelRouting:
        mode: custom
        provider: openai-codex
        model: gpt-5.6-luna
      reasoning:
        mode: custom
        effort: high

modelRouting is either { mode: 'follow-conversation' } or an atomic custom { mode: 'custom', provider, model } record. reasoning independently follows the conversation or stores { mode: 'custom', effort }.

The optional defaultProfile names the delegation tool used when no profile is named; it must exist in profiles. Deleting the current default profile is refused until another default is chosen or the field is cleared.

The plugin does not read the retired $DSH_HOME/custom-subagents.json file. Flat provider, model, and reasoningEffort fields belong to an obsolete pre-release format and are rejected.

Update and uninstall

Update to a specific version

dsh plugin --profile web add github:xie-tj/dsh-subagent#<new-commit-sha>
dsh --profile web

The CLI reconciles the manifest and the cordis.patch.yml layer. Restart the profile to load the new code; existing continuable children keep the route they were created with.

Roll back to an earlier version

Same command, with an older SHA. The CLI does not store a history of past versions, so keep your own notes of which SHA you want to roll back to.

Uninstall

dsh plugin --profile web remove dsh-subagent
dsh --profile web

Removing the plugin removes the dependency from the profile's package.json and the dsh-subagent layer from the resolved composition. It does not delete the dsh-subagent namespace from the settings file. If you also want to wipe saved profiles, edit the settings file (see Where state lives) and remove the dsh-subagent: block manually. Reinstalling the plugin later will not recreate the previous profiles.

Troubleshooting

Symptom	Likely cause	Fix
No "Subagents" section in Settings	Plugin is installed in a profile that does not load the Web UI, or the profile was not restarted after install.	Confirm the profile: `dsh plugin --profile web why
`dsh plugin --profile web add` fails with peerDependency error	DSH core packages are older than `0.1.1-rc.2`.	Upgrade DSH (see your distribution's upgrade steps), then retry.
`cordis.patch.yml` not visible in `dsh plugin --profile web why`	The plugin's manifest was not picked up by the CLI's bundle reconciler, often because the dependency was added manually rather than through `dsh plugin add`.	Re-add through the CLI: `dsh plugin --profile web remove dsh-subagent && dsh plugin --profile web add github:xie-tj/dsh-subagent#<sha>`.
A custom route cannot be saved	The selected Provider/Model/effort is not in the live Host model catalog.	Refresh the catalog from the settings page, or pick a route the catalog currently returns.
Duplicate `subagent_<name>` or `custom_subagent` registration	Another dynamic subagent-profile plugin is mounted alongside this one.	Stop and remove the older plugin before enabling this one.
Deleting a profile reports it as the default subagent	`defaultProfile` still names it.	Pick a different default (or "不设置" / unset) first, then delete.
No provider for `spawn` or `fork`	The profile is missing the subagent providers.	Use a profile that ships them, or add `@deepseek-ai/dsh-subagent-spawn` / `@deepseek-ai/dsh-subagent-fork` (or equivalent) and the `dsh-tool-subagent` capability to the profile.
Settings lost after reinstall	The `dsh-subagent` namespace lives in the settings file; `dsh plugin remove` does not delete it.	Restore from your settings backup, or re-create the profiles through Settings → Subagents.
`defaultProfile` rejected on load	The saved default names a profile that no longer exists.	Edit the settings file and either remove the `defaultProfile` line or set it to an existing profile name, then restart.

Model experience

Model-visible tools: one Agent-scoped delegation tool per profile (subagent_<name>), plus the Agent-scoped custom_subagent management tool.
Prompt and token effects: a child receives the route and reasoning policy resolved when it is created, plus the configured persona, tool filter, depth limit, and backend context policy. While a default profile is set and its tool is mounted, the parent prompt carries one fixed short section; otherwise nothing is added. The parent request does not gain the child's transcript, and this plugin adds no cache layer.
Persistence: profile updates are written through the DSH settings provider and remain available to later sessions in the same profile.

Known limitations and deferred work

Provider and Model choices in the GUI are limited to routes returned by the live Host model catalog. Direct settings can name another registered route, but the GUI has no free-form fallback when the catalog omits it.
The settings section currently ships Chinese field copy while its navigation label follows the Host locale.
dsh plugin remove does not delete the dsh-subagent namespace from the settings file. Wipe it manually if you want a clean slate.

Development

pnpm install
pnpm test

pnpm test runs schema/runtime tests, browser-client registration and rendering tests, and a real Cordis Loader composition lifecycle test.

The repository ships executable JavaScript and does not need a build step for installation.

License

MIT