Plugins as Services
Plugins contribute services to the context, addressed via ctx.<key> (e.g. ctx.tools, ctx.llm, ctx.sessions) rather than importing concrete implementations. Other plugins locate services by key, achieving loose coupling.
Back to Home
DeepSeek AI · Open-Source AI Coding Agent Framework
DeepSeek Hermes
DeepSeek Harness (dsh) is an open-source agent harness developed by DeepSeek AI. It adopts an "everything is a plugin" architecture driven by Cordis — model adapters, tool registries, session logs, and the agent loop itself are all replaceable plugins, with no privileged core to patch.
33k+GitHub Stars
MITLicense
CordisPlugin Framework
rc.6Current Version
What Is DeepSeek Harness
DSH is a framework that turns AI models into operational coding agents — models can read and write files, run commands, delegate work, and maintain plans.
DeepSeek Harness (dsh) is an open-source agent harness developed by DeepSeek AI. It is not a simple code-completion tool but a complete agent runtime: models can read and edit workspace files, run commands, delegate work, and maintain plans. When an operation requires approval under the current permission policy, the Web UI asks the user first.
The core design philosophy of DSH is "everything is a plugin". Unlike traditional monolithic architectures, every component of DSH — model adapters, tool registries, session logs, the agent loop, system prompt assembly, persistence, sandboxing, and approval policies — is a Cordis plugin. This means there is no privileged core to patch: you extend dsh simply by mounting your own plugins next to the others, and all registrations are reversible effects that roll back automatically when a plugin unloads.
DSH is currently in developer preview, iterating rapidly, with breaking changes expected in the future. It is powered by the Cordis framework, whose design is described in the paper "A Programming Paradigm for Spatiotemporal Composability".
Architecture
Cordis is the plugin framework underneath dsh: plugins contribute services, typed events, and reversible effects to a shared context.
Declarative Dependency Injection
Declare required services via inject; the framework ensures dependencies are ready before your plugin loads. Load order is expressed by service requirements instead of manually orchestrated startup sequences.
Typed Events
Services define event names via TypeScript declaration merging, then dispatch them in four modes — emit / waterfall / parallel / serial — for observing, wrapping, concurrent, and sequential handling respectively.
Reversible Effects
Prompt sections, tool schemas, adapters, and listeners are installed via ctx.effect() or ctx.on(), and roll back automatically on reload and unload — no manual removeListener needed.
Core Packages
The core packages that make up the Cordis tree, their responsibilities, and context keys.
core/session
Append-only SessionEvent log with in-memory storage
ctx.sessions
core/system-prompt
Prompt section and tool schema assembly
ctx.systemPrompt
core/tools
Scoped tool registry and protected execution pipeline
ctx.tools
core/agent
Agent interface, active registry, and agent/* events
ctx.agents
core/agent-loop
Default driver implementing the Agent interface
ctx.agentLoop
core/scope
Per-agent scoped registration primitives
library (no key)
llm/llm
Message and streaming vocabulary plus adapter seam
ctx.llm
Turn Flow
A step is one model request plus the tools it calls. A turn is zero or more steps: opened before the first input is consumed, closed when nothing is left pending.
1
turn/start
Consume the next input and one queued message; assemble prompt sections + tool schemas
2
agent/pre-step
Rewrite or reject consumed messages → enter or close the turn (waterfall)
3
step/start
Append the entering message as user/message; derive model history from the log
4
agent/request → llm/stream
Model request → streamed response → assistant/chunk* → assistant/message
5
tool/call* → tools/*
Tool call → pre-execute → execute → post-execute → tool/result*
6
step/end
Tool needs another request, or new input arrives → consume → next step
7
agent/turn-stopping
Serial event with no next(); decides whether to stop the turn
8
turn/end
Turn ends; all events have been appended to the persistent session log
Event System
Events are the extension points; choosing the right domain is the first decision in most changes. Events dispatch in four modes.
| Event Type | Dispatch Mode | Description |
|---|---|---|
| Session events (session/*) | emit | Durable facts appended to the log and broadcast via session/event. Use when facts must survive reloads. |
| Agent events (agent/*) | waterfall / serial | Carry the active agent: inbox, step, status, request, validation, continuation. For observing or intercepting in-flight work. |
| Capability events (fs/*, tools/*, telemetry/*) | waterfall | Attach policies and adapters to seams without import cycles. For intercepting filesystem, tool execution, and telemetry. |
| Turn events (turn/*, step/*) | emit | Durable session events recording the lifecycle of turns and steps, ensuring operations can be replayed. |
Quickstart
Two ways to launch the DSH Web UI, default address http://127.0.0.1:3080.
Run via npm
bash
npx @deepseek-ai/dsh webRun directly with Node.js installed; launches the Web UI.
Run from source
bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh webFor developers and contributors who want to modify the source and submit PRs.
Inspect the current config tree
bash
dsh --profile web --dump-configPrints the plugin tree the machine actually starts with; any line can be replaced with your own patch.
Core Concepts
Understanding these concepts is the foundation for using and extending DSH.
Bundle
An npm package with a config layer attached. It declares a patch file in the dsh.bundle field of package.json, answering "what does this package contribute".
Profile
A directory under $DSH_HOME/profiles/<name> describing a startable composition. It declares dsh.profile, answering "which bundles make it up, in what order".
cordis.patch.yml
A YAML array of patch entries. Each entry targets a line by id and replaces its entire config, or inserts a new line. Later-applied layers win per line.
dsh-base
The first layer of every profile: model adapters, tools, persistence, sandboxing, approval policies, settings, credentials, and telemetry. dsh-web-app and dsh-headless add the application layer on top.
dsh-web-app
A bundle that adds the browser application on top of dsh-base, delivering the full Web UI experience.
dsh-headless
A bundle that adds a one-shot runner on top of dsh-base, with no server — suitable for CI/CD scenarios.
FAQ
How does DeepSeek Harness relate to Claude Code?
DeepSeek Harness (DSH) is an open-source AI coding agent framework (agent harness) developed by DeepSeek AI, positioned similarly to Claude Code. The difference is that DSH adopts an "everything is a plugin" architecture — model adapters, tool registries, session logs, and even the agent loop itself are all replaceable plugins, with no privileged core to patch.
What does "everything is a plugin" mean?
Every component of DSH — model adapters, tool registries, session logs, the agent loop, system prompt assembly, persistence, sandboxing, and approval policies — is a Cordis plugin. You extend dsh by mounting your own plugins next to the others, while registrations are reversible effects that are rolled back automatically when a plugin unloads.
What is Cordis?
Cordis is the plugin framework underlying DSH; its design is described in the paper "A Programming Paradigm for Spatiotemporal Composability". Core ideas: plugins contribute services, typed events, and reversible effects to a shared context; services are addressed via ctx.<key> instead of importing concrete implementations; load order is expressed by service dependency declarations rather than manual ordering.
How do I run DSH quickly?
With Node.js installed, run npx @deepseek-ai/dsh web to launch the Web UI (default http://127.0.0.1:3080). You can also run from source: git clone the repository → pnpm install → pnpm run build → pnpm dsh web.
What are Profiles and Bundles?
A Profile is a named startable composition stored in the Harness home directory, listing the bundles it stacks and holding your own cordis.patch.yml. A Bundle is the distribution format for Cordis config lines and their mounted code — declared in the dsh.bundle field of package.json. web and headless ship as templates with dsh.
How does the DSH event system work?
DSH has three event domains: session events (session/event) are durable facts appended to the log; agent events (agent/*) carry active agent instances; capability events (fs/*, tools/*, telemetry/*) attach policies and adapters to seams. Events are dispatched in four modes: emit (observe), waterfall (wrapping middleware), parallel, and serial.
Is DSH stable yet?
DSH is currently in developer preview and iterating rapidly. The team has explicitly stated that breaking changes will come. Follow GitHub Discussions and release notes for updates.
Where can I find DSH plugins?
You can search the dsh-plugin topic on GitHub to find community plugins. We also maintain the DeepSeek Plugin Library, which offers a complete DSH plugin directory, category browsing, install commands, and development guides.