DeepSeek Harness Workflow: Parallel Multi-Agent Orchestration for Faster Task Execution

Getting Started with dsh

Launch the web UI with npx @deepseek-ai/dsh web, provide an API key (DeepSeek official or OpenAI-compatible), and select a workspace.

Workflow vs. Serial Delegation

Traditional delegation runs agents serially, stacking every intermediate result in the parent context and requiring a model round-trip per step. Workflow lets the model write a JavaScript orchestration script upfront; at runtime the script fans out tasks to many sub-agents in parallel. Intermediate results stay inside the script, and the parent conversation receives only a single JSON final value. The script format mirrors Claude Code's dynamic workflow: a meta identity block plus a body that supports top-level await.

Five Hooks for All Orchestration Patterns

The script API exposes only five hooks, yet they compose to cover fan-out, pipelines, and hybrid groupings:

agent(prompt, opts) – launch a sub-agent and get a structured result.

parallel(thunks) – run a group of tasks concurrently.

pipeline(items, ...stages) – pass a batch of items through successive stages; a failed item becomes null and skips remaining stages.

phase(title) / log(message) – mark progress and emit logs visible in real time in the Web UI.

Example full-repository audit script:

phase('audit')
const results = await parallel(
  args.dirs.map(d => () =>
    agent(`Audit ${d}, output issue list`)))
log(`Completed ${results.filter(Boolean).length} directories`)
return { results }

The script only coordinates; actual work is done by sub-agents.

Live Test: One Prompt, Whole-Repo Audit

In Standard mode, the prompt

"Use workflow to parallel audit each directory under src: spawn a sub-agent per directory for an issue list, then aggregate into a single JSON report."

makes the model generate and run the orchestration script. The Web UI shows phase progress and each sub-agent's start/end; execution records are persisted in the session for replay and review. Official policy: workflow is used only when the user explicitly requests it; one or two delegations still use the ordinary sub-agent path.

Three Design Pillars

1. Meta Is Data, Not Code

Claude Code embeds meta as export const meta inside the script, requiring execution to read it. dsh separates meta as a JSON parameter validated without executing the model-written text.

2. Errors Must Be Loud, Never Silent

Mistyped hook options or out-of-range parameters throw a fatal error immediately. The project states: a typo must not dissolve into a null indistinguishable from a sub-agent failure.

3. Isolation Is Isolation, Security Is Security

Each run executes in an independent worker-thread VM context, but the documentation repeatedly stresses this is not a security boundary; script trust level equals that of a bash script.

Related tool ralph takes a different approach: a fixed loop handing the same goal to a fresh sub-agent each iteration, suited for long-running tasks.

Current Capability Boundaries

Workflow runs synchronously in the foreground: no background collection, no checkpoint/resume after process restart, no token budget or global timeout, and nested workflows are explicitly rejected. These are listed as "deferred non-goals." dsh remains in developer preview; breaking changes may arrive anytime, so pin the version for experimentation.

Summary

Workflow extracts "how to orchestrate" from the conversation into a re-runnable, replayable script—sub-agents do the work, the script schedules, and the parent sees only the final answer. For scenarios with dozens or hundreds of similar sub-tasks, this is a higher-level play than serial delegation. However, it incurs high token consumption; with DeepSeek's weekend off-peak pricing, plan high-efficiency tasks accordingly.