What's a Harness?

An LLM only knows how to do one thing: read text, produce text. It can't open your files, run a command, or remember yesterday's conversation. All that is the job of the surrounding program—the harness. It reads your project's files and hands them to the model. When the model says "run npm test", the harness actually runs it and feeds the output back. If the model wants to edit a file, the harness decides whether to allow it or ask you first.

That layer is a harness. Claude Code is one, Codex is one, and so is Cursor's Agent mode. The same model can behave very differently inside different harnesses, because the harness decides what the model sees, touches, and does when it gets stuck.

Plan Mode, Subagents, Permissions, and MCP All Live Outside the Core

Most agent tools on the market bake all of these in: plan mode, subagents, permissions, MCP, context compression. You can toggle parameters and turn them on and off, but you can't swap them out. If that doesn't work, you can fork the project or wait for the vendor to add an option.

dsh flips that. Its core directory contains just eight packages: session logs, system prompt assembly, tool registry, agent interface, default driver, and scope primitives. None of the features above are in there.

Plan mode is a plugin. Subagents are eleven packages across seven providers. Permission approvals are two packages. MCP integration is a client plugin. Context compression is four packages. Todos, scheduled tasks, and background jobs are each standalone. The UI is split the same way: web UI in apps/web, command line in apps/cli, and a terminal interface requires installing a profile yourself—it doesn't ship with the distribution.

This extends to the agent's main loop. The contributor guidelines are clear: new behavior attaches at documented extension points; if you must modify the main loop, the same commit must update the architecture docs.

There is no privileged kernel that requires patching: you extend dsh by mounting plugins alongside other plugins, and registrations are effects that are undone when their plugin is unmounted.

docs/architecture.zh.md

The trade-off is real: it's in developer preview, and the README warns of breaking changes. Config patches are whole-line replacements, with no deep-merge layer.

Even the Main Loop Is a Swappable Plugin

The foundation that makes all this swappability possible is a framework called Cordis, whose source is vendored wholesale into the repo's vendor/ directory. It lets each plugin attach services, events, and side effects to a shared context; when a plugin is unloaded, everything it attached is automatically undone.

On top of that foundation, every part of the product is a plugin: the model adapter, the tool registry, session persistence, and the agent loop itself.

Here's how it fits together at runtime: a running dsh instance is a plugin tree, assembled by layering configs in order. The base layer is dsh-base, which bundles model adapters, tools, persistence, sandbox and approval policies, settings, credentials, and telemetry. Add dsh-web-app and you get a browser UI; add dsh-headless and it runs one task, prints the result, and exits without starting a server. Your changes go on top.

The whole-line rule applies here: to change one field, you rewrite the entire line, including everything you want to keep.

Everything the Model Sees Must Be Replayable, and Capabilities Come in Threes

Two principles keep this modular architecture from collapsing.

1. Every token the model sees must be reconstructable from the log

The session log is append-only. The context for each request is a projection of that stream. The rule is stated in reverse: anything that reaches a model request must be reconstructable from the log, and a runtime assertion enforces it. So if you want to add something new that the model can see, you must also add a corresponding session event. No sneaking things in.

That gives you sessions that pause, resume, fork, and replay exactly with no hidden model-visible state.

2. A capability requires three roles

dsh defines a "capability" as three roles: the one declaring the interface, the one implementing it, and the one consuming it (usually a tool for the model). All three must be designed together; a missing role means it's not a capability.

Swap the bottom layer and everything follows: filesystem and processes share one environment, so a remote sandbox automatically moves Bash, the persistent terminal, and the language server—no per-tool remote versions. Subagents work the same way. The interface is "take a self-contained task, return a final answer." Whether that's a forked process in the same runtime or a different vendor's product makes no difference to the caller.

Code Mode, ralph, and Self-Installing Plugins

If everything is replaceable, what ships? Around thirty usual suspects: bash, file read/write/edit, glob and grep, web search and fetch, todos, plan mode, language server, persistent terminal (one terminal session that persists across commands rather than spawning fresh each time), background tasks, scheduled tasks, subagent dispatch and messaging, and session_search for browsing your own history. It also integrates with MCP servers, and those tools appear as native tools to the model.

Three other tools stand out.

1. Code Mode: the model writes a program to call tools in bulk

Usually the model calls one tool at a time—the harness runs it, returns the result, and asks for the next step. Searching files then reading a few means many round-trips, and every intermediate result piles into the context.

run_code takes a different approach: the model writes a short TypeScript program that chains calls together with await tools.grep(...), await tools.read(...), etc. It runs the whole thing in one shot, then returns only the final result the model cares about.

2. ralph: a brand-new agent for every single turn

Give it a fixed goal, and it starts a new subagent each turn. That new agent sees none of the previous turns' conversation. Only two things pass between turns: the real files in the workspace (its long-term memory) and a short structured report. It keeps going until a report says done or stuck, or until it runs out of turns.

3. cordis: the agent installs plugins into its own running process

This group has four actions and one read-only report. They operate on the currently running process, not on config files on disk.

Note the "browser half" in step 2: the agent can write a UI on the fly and deliver it directly to the web page you have open. There's also a companion tool, cordis_inspect, that lets the agent read the live state of its own process: which services exist, which plugins are alive, and which tools are registered.

Your Hooks and Skills Just Carry Over

So what does the move cost someone who already uses Claude Code? Most of what you have doesn't need to change.

Existing hooks work unchanged. (Hooks are small scripts triggered automatically at fixed moments, like running a format check before every file save.) dsh ships two bridge plugins: one consumes Claude Code's hooks.json, even handling the ${CLAUDE_PLUGIN_ROOT} and ${CLAUDE_PROJECT_DIR} variable substitutions; the other consumes Codex's hook config. The exit-code convention is also respected: exit code 2 means block the operation and use stderr as the reason. When multiple hooks match, the strictest wins—deny overrides ask, ask overrides allow.

Skills are read directly. It scans for SKILL.md format skills in two places: its own ~/.dsh/skills and a ~/.agents directory, which the config describes as a "shared agent config root scanned for skill compatibility."

It can also hand work back to a real Claude Code. Subagents come with seven providers, two of which are external products: one calls the official Claude Agent SDK and looks for a claude command on your machine; the other launches the official codex app-server --stdio. You send over a self-contained task and get back only the final answer. That Claude Code runs with your existing local account and config—the docs explicitly note it neither copies nor filters these files, nor does it create or modify your login state.

This all works thanks to the trio rule from earlier: the subagent interface is "accept a self-contained task, return a final answer." Anything that satisfies that interface can be a provider, even another vendor's finished product.

The hook bridge has its limits though: native plugins can do everything the bridge does, with more power, types, and no serialization loss. The bridge is a compatibility path so existing configs work today; real customization means writing a native plugin.

The reverse direction also works: DeepSeek's API can directly back tools like Claude Code, GitHub Copilot, or OpenCode, no code changes needed. Swapping the harness and swapping the model are now independent decisions.

If the Sandbox Can't Start, Work Is Refused

But give all these tools to an AI, and what happens when it mistypes a command? This harness has three permission tiers, defaulting to the strictest.

Each platform uses its native mechanism: Linux prefers bwrap, falling back to Landlock (for which they wrote their own C extension); macOS uses Seatbelt; Windows uses ACL-restricted tokens.

The current tier is also communicated to the model as a message, but only once and only when the policy changes. No spam.

DeepSeek's Benchmark Ran with Just Two Tools

So how much of this did DeepSeek actually use when it ran its own benchmarks?

The minimal mode mentioned in the benchmark footnote has its config right in the repo (examples/jsonrpc-agent/minimal.cordis.yml), readable line by line. The model was given exactly two things.

Of the thirty-odd built-in tools listed in the previous section, only two remain here: a stateful bash and a string-replacement editor. The skill system is off, runtime context injection is off, workspace context is off, context compression isn't installed, and even the plain bash tool and background task tool are turned off. The system prompt is the most unremarkable sentence imaginable: "You are a helpful software engineer assistant."

Terminal Bench 2.1's 87.9 and DeepSWE's 62.7 were achieved with this config.

The scores come from the model itself, with no prompt-engineering tricks in the harness underneath. The out-of-the-box harness has everything enabled; what to run is up to you.

V4-Pro's Gains Are Mostly in Getting Things Done

Since the scores are mostly the model's, what exactly did V4-Pro improve? First, a caveat: the table below is the vendor's own.

Official benchmark table. The footnote at the bottom is the one from the top of this article: public Code Agent tasks were tested with DeepSeek Harness (minimal mode). Source: @deepseek_ai

Compared to its own preview, the biggest gains are all in "have the model autonomously complete a job" type tasks.

DeepSWE jumped from 12.8 to 62.7, nearly a five-fold increase. The previous preview was essentially failing this type of task.

Against the competition, it's a mixed bag. On Terminal Bench 2.1, the 87.9 trails Kimi-K3 (88.3) and Fable 5 (88.0), but beats Opus-4.8's 85.0. The 31.8 on AutomationBench is the highest on the table. But HLE—knowledge and reasoning, no tools—sits at 42.7, well behind Fable 5's 53.3 and Opus-4.8's 49.8. DeepSWE's 62.7 also still trails Fable 5's 70.0 and Kimi-K3's 67.5.

The gains cluster in hands-on tasks; knowledge and reasoning barely moved in this release.

The official post also mentions two more things: V4-Pro and V4-Flash both support adjustable reasoning effort—low, high, or max—with the official guidance being low for simple tasks, high for everyday agent workflows, and max for complex ones (the benchmark used max). And there's native support for OpenAI's Responses API, with a one-click setup script for Codex in the official docs: it backs up your existing ~/.codex/config.toml, writes the model metadata, changes only the necessary fields, and preserves your existing MCP server config.

From August 17, Cache-Hit Input Costs 12x More

The same day also brought the third announcement: starting at midnight Beijing time on August 17, API pricing moves to peak and off-peak rates. Peak hours are 9:00–12:00 and 14:00–18:00, totaling 7 hours a day; the other 17 hours are off-peak, at exactly half the peak price.

For deepseek-v4-pro: output is currently ¥6 per million tokens. The new price is ¥13.5 off-peak and ¥27 peak—4.5 times the current rate at peak. Input (cache miss) is ¥3 now, going to ¥4.5 and ¥9.

The biggest jump is the cache-hit input price.

Multipliers calculated by us from the official old and new rate cards; the rates themselves are from DeepSeek's API pricing page.

Why does the cache-hit tier matter? Because agents work turn by turn, and each turn has to resend the entire conversation and all the files it's read. That part almost always hits the cache. The tier with the biggest increase is exactly the tier you consume most when running an agent for a long time.

Concurrency limits are 500 for deepseek-v4-pro and 2500 for deepseek-v4-flash. The official announcement does not explain the price increase.

Of 218 Packages, Each Must Document Its Own Shortcomings

So can you use this today?

It's installable: the first candidate version hit npm on August 10, three more came on the 13th, and the latest is 0.1.0-rc.6. The repo was created at 19:56 that day, and by 22:02 it had 17k stars and 1,182 forks. Fill in your API key, pick a workspace directory, and you're off.

Web UI settings page: the key takes effect immediately, no restart needed; you can also add other providers or custom OpenAI-compatible endpoints. Source: repo docs/user/guide/

But the README's first line is a warning: it's in developer preview, iterating fast, and breaking changes are coming. The internal spec is even blunter: since there are no external users yet, a correct foundation is worth more than a compatibility layer. The session file format version is still at 0, with no compatibility promises whatsoever.

Enforcing this seriousness is a CI gate: of the 219 packages, 218 must have a "Known Limitations and Deferred Work" section in their README. Miss it, and the build fails. The single exemption is a package containing only type definitions, and even that exemption must document why it has no limitations.

A few highlights:

What to Install and Run

Just want to use it: Install Node (22.19+ or 24+), run npx @deepseek-ai/dsh web, open the address it prints in your browser, and put your DeepSeek API key in Settings (no restart needed). Then click "Choose Workspace" to add and select your project directory—the input field stays disabled until you do. For operations that need approval, the UI asks you first.

Want to hack on it: In addition to Node, you'll need Corepack-enabled pnpm (the repo pins 11.7.0) and Git 2.26 or newer. Clone, run pnpm install, then run pnpm run typecheck once. If that passes, your environment is set up. Installation also hooks in Git scripts: a pre-commit hook runs lint and auto-fixes, and a pre-push hook runs the type check.

TODO markers in the code come in three flavors: FIXME means release-blocking, must be resolved before a stable release; TODO means should do when there's time; XXX means "if I think of it"—no commitment.

Plan mode, subagents, permission approvals, MCP integration—other agent tools weld these into the core. dsh's core directory has just 8 packages; all that functionality lives outside as plugins. Even the agent main loop itself is swappable.

Already using Claude Code or Codex? No need to rebuild your setup: your hooks.json works as-is, your SKILL.md files are readable as-is, and it can even hand sub-tasks to a real Claude Code on your machine.

The V4-Pro benchmark footnote says the public Code Agent scores used dsh in minimal mode, and that config file is right in the repo. Note: the data is DeepSeek's own, with no third-party replication.

The system prompt was a single sentence: "You are a helpful software engineer assistant." The scores are basically all model.

Same day, the official notice: from midnight August 17, API pricing moves to peak and off-peak. Agents work turn by turn, resending the whole conversation and files each time—and that's almost all cache hits (same content sent repeatedly is billed at a lower rate). The tier with the biggest jump is exactly that one.

That's the v4-pro cache-hit input price: a 12x increase. Output goes up 4.5x. Concurrency caps: 500 for v4-pro, 2500 for v4-flash.