DeepSeek Harness Deep Dive: How a Modular “Heart” Powers Flexible AI Agents

All is plugin, execution traceable.

What Is DeepSeek Harness

DeepSeek Harness (DSH) is DeepSeek's first open‑source agent framework, released under the MIT license. Its slogan is "All is plugin." Shortly after release it attracted over 60 000 stars and 5 000 forks on GitHub. It is not merely a coding tool but a foundational framework that enables agents to act.

The official formula is Agent = Model + Harness . The model only "thinks"; the Harness "does"—handling file I/O, command execution, web search, sub‑tasks, context management, and user interaction. None of these capabilities are built into the model; they are supplied by the Harness.

While many companies are racing to build the "execution layer," DeepSeek chose to make the layer itself a freely composable framework, allowing anyone to assemble their own agent. The name "Harness" (meaning a bridle or reins) reflects the idea of putting a saddle on a wild horse (the model) so it can truly run.

All Is Plugin

DSH is built on Cordis, Latin for "heart." Cordis manages plugin loading, unloading, and dependencies, but provides no concrete functionality itself—its capabilities come entirely from plugins.

Model : adapters for nearly 40 model providers (Kimi, OpenAI, Anthropic, Google, DeepSeek, etc.).

Tools : file editing, shell, web retrieval, search, and external tools following the standard MCP protocol.

Skills : operation manuals that guide the model step‑by‑step for specific tasks.

Session & Storage : session logs, context management, file system, credentials.

Sandbox & Approval : process sandbox and permission policies that limit what an agent can touch.

Main Loop : the entire "think → invoke tool → observe result" cycle is itself a plugin.

UI : the browser UI is also a plugin; the default skin is just one option.

No part of the core is immutable: changing model reasoning, tool behavior, or UI requires only swapping or adding plugins, never modifying source code. The architecture documentation states there is "no privileged kernel that needs patching."

Configuration is layered. A profile defines a named assembly of plugins, and a cordis.patch.yml file can override parts of it. Adding a tool, swapping a model, or extending the UI is done by editing configuration. The community quickly produces hundreds of plugins, such as long‑term memory across sessions, self‑evolving back‑ends, desktop pets, or completely redesigned UIs.

DSH even lets an agent load and unload plugins at runtime, matching capabilities to the task on the fly.

Execution Is Traceable

Everything the model sees—system prompts, chain‑of‑thought, each tool call and its result, sub‑agent actions, context injections—is recorded in an append‑only session log.

This log powers the Trajectory view, which shows step‑by‑step decisions, enabling quick identification of wrong choices or unexpected tool outputs. The log also supports recovery, forking, and replay : a long task can resume from any node, a session can branch into an independent path, and a full execution can be replayed for post‑mortem analysis.

Because all actions are logged, debugging an agent becomes a matter of inspecting the log rather than guessing its internal reasoning.

Built‑In Modes

DSH uses "Agent presets" to bundle identity, rules, tools, and workflows for specific tasks. Four official presets are provided:

Standard Mode : a full‑featured coding agent with file editing, shell, search, skills, planning, goals, sub‑agents, and workflows—suitable for everyday coding and bug fixing.

PTC Mode (also called code mode): retains all standard capabilities but supplies tools to the model as generated TypeScript code, allowing multi‑step operations to run in a single batch. This reduces round‑trips, increasing throughput for bulk searches, parallel file reads, and automated pipelines.

Minimal Mode : only a persistent bash and a file‑editing tool are present; everything else (search, skills, sub‑agents) is omitted. DeepSeek used this mode for the V4‑Flash benchmark to isolate pure tool‑use and coding ability.

Creation Mode : a meta‑mode that includes all standard features plus the ability to experiment with Cordis plugins in‑memory and compose a custom preset—ideal for DIY agents.

An additional headless mode runs without a UI: dsh --profile headless "task" executes the task and prints the final answer, making it suitable for scripts and CI integration.

Getting Started Is Simple

Only Node.js is required. npx @deepseek-ai/dsh web Then open the browser at http://127.0.0.1:3080. To run from source, clone the repo, install dependencies, build, and start: pnpm dsh web Switch profiles for headless operation or manage plugins with dsh plugin. The command‑line tool itself is lightweight.

DSH is friendly to context caching: system prompts remain stable across rounds, so as long as the conversation history is unchanged most requests hit the KV cache, dramatically reducing token usage and cost for high‑frequency API calls.

DeepSeek's own models are fast; the author measured over 140 tokens/s, comparable to local models, making DSH cheap, fast, and fully traceable in daily use.

What It Adds Over Claude Code / Codex

Framework Layer : not a fixed product but a chassis that can be assembled into countless agent shapes.

Plugins Reach the Core : system prompts, tool registries, session storage, sandbox policies, UI, and even the main loop are replaceable plugins.

Model‑Agnostic : supports nearly 40 model providers out of the box; users can swap models freely.

Full Execution Trace : every step is logged, with built‑in recovery, forking, and replay.

Open Source with MCP Support : the code can be audited or modified locally, and external tools can integrate via the standard MCP protocol.

Future Directions (Speculative)

The current "local service + browser UI" is likely just the first skin. Based on the architecture, the author speculates the following paths:

Desktop App : wrapping the service and UI with Electron or Tauri to create a native desktop application.

Interactive CLI / TUI : headless mode already runs from the command line; examples like dsh --profile tui --resume <id> hint at a full‑screen terminal UI for power users.

Embedding in Other Products : the plugin architecture makes DSH suitable as an "Agent backend" for IDE extensions, low‑code platforms, or internal enterprise systems.

Cloud Deployment : sandboxing can be moved to remote servers, models accessed via API, and session logs synchronized, enabling official cloud services, multi‑device sync, and shared workspaces.

These are conjectures; the official team has not confirmed any roadmap. What is certain is that DSH's architecture imposes no hard‑coded constraints, so any of these directions are technically feasible.

Conclusion

DSH impresses not because it bundles many tools or runs fast, but because of two principles: "All is plugin," turning agents into Lego‑like constructs, and "Execution is traceable," converting opaque AI behavior into auditable engineering. It may not replace existing products immediately, but it points to a new focus on the execution layer as the next battleground, with DeepSeek already diving in.

The future will depend on how the community assembles new plugins and use‑cases on this open chassis.