herdr-bridge

A dsh plugin that bridges a DeepSeek Harness web session to Herdr, letting the dsh agent discover, start, prompt, and observe other agents (pi, claude, codex, ...) running under Herdr — all from inside the dsh web UI.

Requirements

• dsh (npx @deepseek-ai/dsh or a local build) with the web profile
• Herdr running on the same machine (herdr CLI on PATH, socket at ~/.config/herdr/herdr.sock)
• Node.js >= 20

Install

From GitHub (published source):

dsh plugin --profile web add github:damozhang/dsh-herdr-bridge

From npm (once published):

dsh plugin --profile web add dsh-herdr-bridge

From a local checkout (development):

dsh plugin --profile web add /path/to/herdr-bridge

Then restart the dsh web server so the bundle is loaded. To update to a newer version, run add again with the same source (pnpm caches; remove first if you switch sources). For active development, link the local checkout — source edits take effect on the next server restart — and switch back to the GitHub source to validate what others will install.

Starting dsh so Herdr integration works (important)

Herdr's own skill refuses to act when the agent process is not Herdr-managed: it checks HERDR_ENV=1 in the environment and stops otherwise. The dsh web process must therefore run with HERDR_ENV=1 set, otherwise the dsh agent will refuse to touch Herdr even though this plugin is installed.

Option A — recommended: run dsh web inside a Herdr pane

Herdr automatically injects HERDR_ENV=1 (and HERDR_SOCKET_PATH/HERDR_PANE_ID) into every pane it manages. Create a pane bound to your usual working directory and run:

npx @deepseek-ai/dsh web

The web server inherits the Herdr environment, the skill gate passes, and the server's own output stays observable in that pane.

Option B — run in a plain terminal with exported environment

If you prefer the web server outside Herdr, export the markers first:

export HERDR_ENV=1
export HERDR_SOCKET_PATH="$HOME/.config/herdr/herdr.sock"
npx @deepseek-ai/dsh web

This satisfies the skill check but is less "native" than running inside a Herdr pane.

Verify

Open the dsh web UI and ask the agent to herdr_agent_list. If it returns the live Herdr agents (with pane ids), the bridge is working. If the agent refuses with a Herdr environment error, the server was started without HERDR_ENV=1.

The plugin's tools also set HERDR_ENV=1 and a default socket path on every spawned herdr CLI call, so tool execution itself is resilient; the process-level variable is what the skill gate checks.

Tools

Tool	Purpose
herdr_agent_list	List Herdr agents (pane id, status, cwd) to discover collaboration targets
herdr_agent_start	Create a workspace and start an agent (kind: pi, claude, codex, ...; optional model)
herdr_agent_prompt	Send a message to an agent by pane id, wait for completion, return its output
herdr_delegate	One-shot: start agent → submit task → wait → return output (optional cleanup)
herdr_pane_run	Run a shell command in any pane and read its output (optional match-wait)
herdr_workspace_close	Close a workspace to clean up its agents and panes

Examples

Ask the dsh web agent:

herdr_delegate: review /path/to/code with model opencode-go/deepseek-v4-pro

or compose primitives:

herdr_agent_list
herdr_agent_start pi in /path with model opencode-go/deepseek-v4-pro
herdr_agent_prompt <paneId> "implement feature X and run the tests"
herdr_workspace_close <workspaceId>

Development

pnpm install        # installs devDependencies
pnpm run build      # compile src/ to dist/ — required before committing a source change
dsh plugin --profile web add /abs/path/to/this/repo

dist/ is committed on purpose. The plugin ships compiled JavaScript: main points at dist/index.js, never at src/index.ts, because Node refuses to strip types from any .ts file resolved under node_modules — and dsh plugin add always installs into node_modules. The build cannot be deferred to install time either: pnpm rejects a git-hosted package that carries a prepare (or any build) script unless the consumer allowlists it in pnpm-workspace.yaml, which would break dsh plugin add github:... for everyone. Committing the build is what keeps all three install sources working with no consumer configuration.

So: run pnpm run build and commit dist/ in the same commit as any src/ change, or installers will get the previous build.

@deepseek-ai/dsh-tools is a peerDependency, not a regular dependency, so the plugin binds to the single copy the host dsh runtime already loaded instead of pulling a second, possibly stale one into the profile.

Schema notes: the dsh value-schema DSL is stricter than JSON Schema — required lives per-field, and object schemas must declare additionalProperties explicitly.

License

MIT