DeepSeek Harness: Everything Is a Plugin

On August 13, 2026, DeepSeek AI opened a repository called DeepSeek Harness — dsh, an open-source agent harness in TypeScript, MIT-licensed, whose one-line description is the whole design: "Everything is a Plugin." Four days later it had more than 149,000 GitHub stars, and the count was still climbing toward 150,000 as this post was written. That is an extraordinary reaction to any repository, and it is even more extraordinary for one that is explicitly a developer preview promising compatibility-breaking changes, with no external plugin ecosystem yet and no tagged stable release (the shipped artifact is 0.1.0-rc.7).

This blog met this repository's intellectual foundation two days after it appeared. On August 13 — the same day the Harness repository went public — an 88-page paper was published from the cordiverse/paper repository: A Programming Paradigm for Spatiotemporal Composability, by Yifan Shi and Wei Zhang of Peking University and Tianyi Cui of DeepSeek-AI. I summarized and reflected on it in Spatiotemporal Composability: The Missing Calculus for Self-Evolving Agents. The paper formalizes dynamic composition — components loaded, unloaded, and reconfigured at runtime — with two guarantees: temporal composability (when a component is removed, everything it did is undone) and spatial composability (when the world changes, components whose dependencies changed reconnect or wait, never crash). Its authors extracted the theory from Cordis and Koishi, a plugin framework and a chatbot framework with 4,000+ community plugins — which is why the theory did not arrive as a proposal: it was distilled from software that had already shipped.

DeepSeek Harness's README says in its second line: it is "powered by Cordis, whose design is described in A Programming Paradigm for Spatiotemporal Composability." The calculus this blog called "the missing calculus for self-evolving agents" is not a proposal anymore. It is the runtime under DeepSeek's own agent harness. This post reads the documentation site — deepseek-harness.github.io/deepseek-harness/en/ — the way the project's own docs ask a reader to read it, then distills the key design decisions as insights, each compared against other harnesses, and reflects on what the design actually buys and where its guarantees stop.

The documentation is part of the design

The English docs live at a VitePress site that mirrors a bilingual source tree in the repository — every page is projected from Markdown in docs/, with a Chinese counterpart kept in sync by a custom Git merge driver. The landing page is a one-line redirect to Guide → Use the Web UI, which is the honest shape of the project: the fastest path is npx @deepseek-ai/dsh web, which serves a web UI at http://127.0.0.1:3080, where you add a DeepSeek API key, choose a workspace, and send the agent a task.

Three nav sections matter more than their titles suggest. Guide is user-facing (Web UI, model configuration, a Python SDK). Development is plugin authoring, including a seven-part Cordis tutorial. Reference is the interesting part: an architecture page, a Cordis primer, capability seams, the agent lifecycle, the tool execution pipeline, then a long list of subsystem pages — one per capability (sessions, tools, shell, sandbox, approval, compaction, skills, subagents, workflows, and more) — each ending in a generated Cordis API section with the exact service methods and event signatures, byte-identical to the source, freshness-checked by a build gate so a JSDoc edit cannot ship without regenerating the catalog. The docs also include generated catalogs of every plugin config field, every model-facing tool schema, and every durable session event.

This is not documentation hygiene trivia; it is a design decision worth naming early. The repository treats its documentation as a machine-checked artifact: type declarations pasted into docs are verified drift-free against source (verify-type-equiv), generated catalogs must be byte-fresh (verify-cordis-catalog), and the AGENTS.md documentation standard enforces word budgets per document tier. The reason is stated plainly in the architecture page: "We recommend using an agent to explore the codebase." The documentation is written to be read by agents — which is exactly what a harness company's documentation should be, and almost none of it is.

Key design decisions, read as insights

The section above read the docs as a map. This section reads the code and the design records as a set of decisions — each one a choice with an alternative that lost, recorded in the repo's own Agent Notes, and a comparison that makes the stakes visible. Two framing notes. First, DeepSeek Harness is not the first harness to reach several of these destinations: OpenHands built an event-stream backbone years earlier, SWE-agent argued that the interface between model and computer is the product before DeepSeek shipped one, MiniCode's conversation client is the explicit reference shape behind the request pipeline, and the Claude Code and Codex hook protocols are things the harness implements as a bridge rather than invents. Second, the comparisons below are drawn from each harness's own documentation and code, not from marketing — and the second research pass added source-level findings the docs alone would not have yielded: the compaction checkpoint format, the hooks.json bridge, and Typert's type-graph generator, each covered in its own insight.

Insight 1 — History is the boundary: the append-only log, enforced

The spine of the design is the session log: an append-only log of typed events from which the model's message history is derived by a pure fold, never stored. What makes the decision an insight is the enforcement, which the source makes concrete. Every message-producing append must carry a surfaceOp marker and sourceEventSeqs; the surface manager throws on a raw event without a marker, on a tool/result replacement that changes anything but content, on a non-contiguous sequence number. The derived messages are shared, deep-frozen objects — "mutating logged history through a projection is unrepresentable (it throws)". The turn flow (claim → agent/pre-step → step/start → model request → tools → step/end → agent/turn-stopping → turn/end) is the same shape at every level: durable facts on the log, live control on agent/* events.

The comparison that frames the decision is inside the repo's own note: MiniCode's LLMClient, a stateful conversation client "appended to — never rebuilt — as the conversation advances". DeepSeek adopted the discipline and rejected the shape: a client is "a second operative truth beside the log — the two drift and nothing notices". OpenHands is the closest architectural cousin — its EventStream of actions and observations is also the backbone, replayable and searchable — but the LLM context there is derived by each agent implementation rather than gated by one logged-surface invariant, and the stream is a coordination backbone more than a billing boundary. Claude Code keeps JSONL transcripts for replay, but the transcript is not the source of the next request. Aider uses git as its history — a version of "never rewrite the past" at a much coarser granularity.

The current generation splits into the same two answers with different mechanics. Gemini CLI ships "conversation checkpointing to save and resume complex sessions" — snapshots, not an immutable log. Claude Code's checkpoints roll back the working tree through git: they undo the files an agent changed, not the conversation that changed them. DeepSeek's is the third answer — an append-only log from which everything derives. The other two make the past recoverable; this one makes it unchangeable.

The insight: history is not a record of the agent; it is the boundary of what the agent can do. A harness that edits history gives the model a world where the past is negotiable. DeepSeek's gives it a world where the only move is to append.

Insight 2 — The loop is a row: microkernel over monolith

A running dsh is a plugin tree composed at boot from ordered layers. A profile is a named composition (web and headless ship as templates); a bundle is a distribution format — config rows plus the code they mount (dsh-base is the first layer of every profile; dsh-web-app adds the browser; dsh-headless is a one-shot runner with no server). Layers apply to an empty entry list in order, and a patch targets a row by id and replaces its whole config, or inserts new rows. dsh --profile web --dump-config prints the tree your machine actually boots, and the docs' claim is total: "any row it prints can be replaced by a patch of your own." The model adapter, the tool registry, the session log, the agent loop itself: all rows.

The framework beneath is Cordis, in five ideas: a plugin is an object that implements Service; a context is a repository of services (ctx.sessions, ctx.tools, ctx.llm, ctx.agents, ctx.agentLoop); dependencies are declared via inject so load order is expressed as requirements; services communicate through typed events dispatched as emit, waterfall, parallel, or serial; and registrations are reversible effects — installed through ctx.effect() or ctx.on() so reload and teardown unwind them. The microkernel note records why: the alternatives (a koa-style middleware stack, an explicit phase state machine plugins insert into) would "re-implement dispatch, disposal, and reload semantics that Cordis's native event system already provides"; as Cordis effects, listeners get HMR and disposal for free. The loop itself is a plugin — @deepseek-ai/dsh-agent-loop is "the only concrete loop plugin and is itself swappable — nothing outside it may depend on it".

The comparison sharpens the wager. Claude Code's hooks are the closest mainstream analog — a fixed, documented surface of matcher-grouped extension points — but you cannot add an extension point without the vendor shipping it, and hooks are policy, not composition. LangGraph and AutoGen treat the loop as a graph the developer authors; DeepSeek treats it as a row the developer can disable (disabled: true on the loop's config rule means there is no agent). VS Code's extension host is the classic microkernel, and its "Developer: Reload Window" button is the price of dynamic composition without reversible effects — the exact problem the spatiotemporal paper formalizes. The trade is real, and the repo pays it in incident reports: twice, a quiet configuration mistake silently broke the product, and there are now 27 pre-release checks that catch that class of mistake.

Insight 3 — Policy runs in waterfalls; the final denial is a monotonic guard

Every tool call passes through a pipeline the docs render as a flowchart, and the ordering is the doctrine: waterfalls for extensible policy, guards for final authority. tools/pre-execute runs as a waterfall — hooks, permission, sandbox decisions; a listener that owns the decision short-circuits by returning without next(). Then monotonic guards run — they deny or abstain and can never force-allow, so owner policy that must not be reordered cannot be argued around. The approval seam is fail-closed: allowed-once is the only granting outcome; a missing, throwing, or non-conforming answerer resolves to unavailable. Then tools/execute wraps the tool body as around-dispatch (timeouts, retries, metrics), tools/post-execute may accept, block, or rewrite, and a definition-owned finalizeContent callback — snapshotted at the moment the call starts, so no later mutation can change what the outcome must be — enforces the last content-only invariant before the frozen tools/result.

Two details show the care. A call collapsed by code mode (see Insight 6) is denied before the policy pipeline — "pre-execute listeners, approval ask, and guards must never observe — or worse, approve — a call that can only fail". And cancellation is a contract, not a cleanup: the registry tracks whether the tool body started and distinguishes ABORTED_BEFORE_DISPATCH from ABORTED, fusing the caller's signal into any around-wrapper replacement so "cancellation never abandons the body". The enforcement layer hangs off the same pipeline: sandbox modes (read-only / workspace-write / danger-full-access, filesystem effects only, enforcement reported full or partial), permission presets (workspace-write+ask, danger-full-access+never), the scrubbed-env and private-temp-file rules from the defensive-patterns ledger. The local backend is worth one more sentence: it functionally probes competing confinement candidates — bwrap then Landlock on Linux, Seatbelt on macOS, a Windows ACL restricted-token runner — picks the first that actually works on this kernel, and fails closed if none does; on Windows, every workspace gets a standing SID grant while each live session receives a random private temp directory with its own capability, revoked on dispose.

The comparison: Claude Code's permission system (allow/deny/ask) and hooks cover the same roles, but they are configured surfaces; SWE-agent's ACI is a fixed, deliberately minimal interface; OpenHands routes policy through a security analyzer. The DeepSeek distinction is the ordering guarantee — extensible policy upstream, monotonic final denial downstream — plus a fail-closed approval contract with a single answerer.

Insight 4 — A capability is a seam, not an interface

A swappable capability has three roles that change at different rates: a Service Definition owning the ctx.<key> and the vocabulary, one or more Service Providers implementing it, and a Consumer (usually a model-facing tool) programming against it. The capability-seams note records why: "swapping a local executor for a sandboxed one would churn the tool schemas the model sees, even though the model-facing contract never changed." packages/shell is the reference template — dsh-shell (definition), dsh-bash-local / dsh-bash-sandbox (providers), dsh-tool-bash (consumer) — and the rule is to split only when roles evolve independently. The subagent seam shows the payoff: providers registered by name include in-process spawn, fork, ACP, Codex, Claude Code, and the dsh SDK itself, all behind one interface; a provider advertises its start-time capabilities statically, and a request needing one it lacks is rejected loud before any run exists.

The comparison: MCP is the industry's attempt to standardize the tool seam, and DeepSeek supports it — but treats it as one consumer family, not the seam itself; the seam is the three roles behind a stable context key. Codex and Claude Code each ship one implementation of each capability. The subagent registry's use of the vendors' own kits (Anthropic's agent kit, OpenAI's app server) is the inverse move: instead of reimplementing a rival harness, mount it as a provider.

Insight 5 — Interop as product strategy: adopt rivals' formats

The seam philosophy has a product-strategy face, and it is visible in three places where the harness deliberately implements other products' formats. The Claude Code hooks bridge reads a real hooks.json — the matcher-grouped configuration Claude Code itself uses — and runs unmodified hooks (SessionStart, PreToolUse, PostToolUse, Stop, subagent hooks) against DeepSeek's typed extension points, mapping Claude's decision vocabulary onto them. The compaction engine produces a checkpoint in the same eight-section structured Markdown that Claude Code's own auto-compact produces — "Primary Request and Intent", "Files and Code", "Next Step", and the rest — delivered as the trailing user message, so a session compacted by one harness can be resumed in the other's shape. The subagent backends start the vendors' own binaries and speak their own protocols. And the workflow engine's meta block "matches the Claude Code dynamic-workflows meta block" verbatim.

The strategy is consistent: when you adopt a rival's format, their files and their habits become portable into your product — the side effect Aaron's teardown names. But it cuts both ways, and the insight is the tension: the harness is a compatibility layer for the vendors' surfaces, not a standard-setter. The one format DeepSeek is not adopting is the one it hopes to set — the append-only, prefix-preserving history model. That is the bet with a deadline this post returns to in the reflection.

Insight 6 — Code mode: the tool list is a presentation, not the interface

The tool registry owns presentation modes — native, code, both — chosen by config. In code mode, the model gets a generated TypeScript SDK over the visible tools plus one reserved run_code transport: it writes a program that loops, branches, and runs several reads at once, and only what it prints or returns comes back into the conversation. The note's framing is borrowed openly from Cloudflare's Code Mode: "LLMs are better at writing code than at emitting tool calls, because they have seen millions of lines of real code and comparatively few contrived tool-calling traces." The program runs in a fresh worker thread with an empty environment, heap and wall-clock caps, and hard termination — and the trust posture is stated without hedging: run_code is "bash-equivalent by design — no unsafe-acknowledgement flags — because the harness already ships dsh-bash-local, which executes arbitrary model-written shell commands with strictly more ambient authority." Every sub-call traverses the full tool pipeline with the parent's token; deferred contexts are held until after the outer result so call/result adjacency survives.

The comparison: Cloudflare's Code Mode is the cited antecedent; SWE-agent's ACI research is the academic antecedent of "tool design is the product" — its authors found that the choice and shape of editing and search tools mattered more than the model. Most harnesses still present tools as JSON-schema lists and round-trip every intermediate result into context. The workflow seam takes the same principle one level up: the model writes an orchestration script — with agent() calls that spawn subagents under caps, executed in a vm realm inside a per-run worker thread — so the model curates not only its own context but the delegation tree.

Insight 7 — The type system is the runtime's mirror

Under the whole stack sits a mechanism no other harness in this comparison has: Typert, a compiler-independent TypeScript type-graph analyzer that extracts a model of the codebase's types, services, and events from the source and emits artifacts from it. The same analysis produces the Host↔Client RPC contracts (methods marked @Remote), the tool-schema catalog, the docs' byte-identical Cordis API sections, the code-mode SDK the model programs against, and the API catalog the cordis_inspect tool serves to the agent mid-session. One representation, five consumers — and the consumers include the model itself.

The comparison makes the move legible. Most harnesses hand-write their API docs or derive them loosely; MCP defines tools at runtime; TypeScript type reflection is usually spent on runtime validation (zod-style), not on generating the agent's own view of the runtime. DeepSeek's version means the docs page, the RPC boundary, the model-facing SDK, and the self-inspection tool cannot drift from each other or from the code — the freshness gates (verify-cordis-catalog, verify-type-equiv) are the enforcement. It is the mechanism that makes the "documentation is written to be read by agents" claim true: the agent reads the same generated contracts the docs print.

Insight 8 — The request is a frozen artifact; the bill is the assertion

In the loop source, every request is composed the same way: the header folds from the log (logged as request/header with reasons initial, resume, or change), the agent/request waterfall may propose the config, and the final GenerateOptions is deep-frozen and marked so the invariant checker can recognize conversation work. The invariant module — a separate companion plugin — replays the log in a fresh session on every request and compares its derivation against what the loop is about to send: "the live cache cannot vouch for itself." The rejected alternative, recorded in the note, is the telling one: detect-and-report (compare consecutive requests, warn on divergence) was refused because "a warning arrives after the bad request has already shipped." On top sits a paid test run against the real API that fails unless the second request in a conversation reports cached input tokens. The bill is the assertion.

The comparison: no mainstream harness ships an invariant checker over request reconstruction. Claude Code and Gemini use provider prompt caching, but the discipline is configuration, not a gate; providers report cache reads in usage, but harnesses do not fail builds on them. The bill-as-assertion is the design's most novel move — the test suite includes the price.

Insight 9 — Per-agent scope: registration is visibility and lifetime

The scope primitive makes one fact drive both: a registration made through an agent's agent.ctx is visible only to that agent and owned by that agent's lifetime. Scoped registrations shadow global ones — the per-agent persona and per-agent tool-variant mechanism — and scope-filtered dispatch carriers route an event about one agent's activity to that agent's listeners. The setup window — after the agent object exists, before it is published — is where a creator composes an agent's scoped world.

The comparison: VS Code scopes contributions to extensions, not per-instance; OpenHands sessions are per-conversation, but capability sets are largely global; LangGraph threads state explicitly through the graph. DeepSeek's per-agent plugin mounting is what makes the four presets (standard, code, minimal, creation) work as per-session compositions instead of global profiles — and it is what makes the "one row" claim in Insight 2 honest: the row can be scoped to a single agent.

Insight 10 — The training environment is the product

The minimal preset is a two-tool composition — a persistent shell plus str_replace_editor — with a system prompt of exactly one sentence: "You are a helpful software engineer assistant." The repo's own note names its purpose: the minimal preset owns the complete Claude SWE-compatible RL agent composition, with the persistent bash environment the RL harness uses. The harness produces the trajectories; the trajectories feed post-training; the trained model goes back to work inside the same harness. DeepSeek open-sourced a piece of that loop.

The comparison makes the decision legible. SWE-agent was built explicitly to produce RL training trajectories — the ACI paper is the academic origin of "the interface is the design lever". terminal-bench-rl trains long-horizon terminal agents with GRPO at 32×H100 scale and reports the sharpest version of the insight: harness-level improvements ("native tool calling, multimodal support, execution optimization") lifted scores without training. Meta-Harness (Stanford IRIS) reached 76.4% on Terminal-Bench 2.0 and was itself "discovered through automated harness evolution". The harness is not just the product — it is the curriculum, and the community is now evolving it like a hyperparameter.

Insight 11 — The harness builds the harness

The repository's AGENTS.md is a standing-order document for agents; decisions live in Agent Notes that must ship in the same PR as the decision, each with an "alternatives considered" section; generated catalogs are freshness-gated; keyless snapshot tests replay a recorded session log against expected output; per-file 100% coverage is the CI gate; and the self-referential toolset (cordis_inspect, cordis_mount, cordis_unmount) lets the agent inspect and mount plugins into its own live runtime, with unmount waiting for every owned effect to reach quiescence.

The comparison: CLAUDE.md and AGENTS.md instruction files are now industry standard — Codex, Cursor, and Gemini all adopted them — but the enforcement is the unusual part: notes as PR gates, verify-* generators that fail on drift, postmortems that do not count until their check is proven to turn red, word budgets per document tier. The teardowns' numbers — 12,293 commits in 64 days, more Markdown files than TypeScript files — are what that enforcement buys. And the self-referential toolset is the honest statement of the whole design's posture: the vm is an API narrowing, not a security boundary — "an opt-in development tool with bash-equivalent trust."

Two teardowns of the same codebase

Within two days of the release, two independent teardowns went up: Cloud Codes' 21-minute DeepSeek Harness Architecture: Insane Software Engineering Behind It (Aug 15) and Aaron — AI-native builder's 10-minute What I Learned From DeepSeek's Harness (Aug 16). Both read the same repository and converged on the same two findings: the session log is a billing design as much as a correctness design, and the harness — not the model — is the product. The insights above read the design the way its authors record it — docs, source, and decision notes. The teardowns read it the way a skeptic would: what is this worth, what does it cost, and what breaks? Both videos pin their claims to the repository, and I checked their key claims against the repo's own Agent Notes and the shipped config files before writing this section; the two videos corroborate each other on the facts that matter.

The golden rule is worth 120x

The Cloud Codes video opens with the rule it found buried in the codebase: "Once something has been sent to the model, you do not go back and change it. A wrong file path sitting in the history, you leave it there and append a new line saying it was wrong." That sounds like bookkeeping. On DeepSeek's own price list it is worth about 120 times.

The mechanism is prefix caching. Because the model forgets, every step resends the whole conversation from the top — a serious coding session pushes past 100,000 tokens through the pipe on one step, then does it again seconds later. Providers rescue the economics with prefix caching: if the leading tokens of this request are word-for-word identical to the last one, the provider restores the computation it already did and starts at the bookmark. Word-for-word is the entire condition — change one character on page three and the bookmark is worthless, the book gets read again. DeepSeek publishes exactly what that costs, which is unusual: at launch-week prices on the pro model, a cached input token runs about a third of a cent per million tokens; the same token uncached runs about 43.5 cents. That is the teardown's arithmetic — it rounds to 120x — for identical text in two neighboring columns of one price table, the difference decided entirely by whether the harness disturbed something it had already sent.

So the real design question for a harness is not which tools to offer or how to word the prompt; it is: can you run a 200-step session without ever going back and editing what you already sent? Most harnesses answer no, because agents edit their history — summaries replace old turns, bulky tool output gets trimmed, a stale file copy gets swapped for a fresh one. Every one of those is sensible; every one reaches backwards into the transcript; every one throws the bookmark away at exactly the moment the conversation is longest and rereading costs the most.

DeepSeek's answer is the append-only log this post already described, and the video's account matches the repo's own Agent Note (2026-07-05-reconstructable-requests) almost verbatim: model-visible ⟺ durably referenced — anyone holding the log, its referenced objects, and the pinned code version reconstructs every loop request byte-for-byte. The note adds the sentence that tells you this team understood their own design better than most write-ups of it: "Prefix-cache stability is corollary #1, not the headline" — "stability is emergent, not managed." They did not set out to build a cache optimizer; they built a log you cannot edit, and the prefix stability fell out the other side.

The note also records the enforcement they chose and the alternative they rejected. Derived messages are deep-frozen — mutate logged history through a projection and it throws, so breaking the rule stops being something you avoid and becomes something you cannot express. The rejected alternative was detect-and-report: compare consecutive requests and warn on divergence — rejected because a warning arrives after the bad request has already shipped. Instead they shipped a module whose entire job is to disbelieve the agent loop: on every request it builds a fresh session, replays the log from the beginning, derives the messages again from scratch, and compares its answer against what the loop is about to send — "so the live cache cannot vouch for itself." On top of that sits a paid test run against the real API with a real key that fails unless the second request in a conversation reports cached input tokens. The bill is the assertion. Cold cache, red test.

The video's best story is the compaction bug that shows the design paying for itself. When a conversation outgrows the context window, the harness must summarize the old part so the work can continue — and the first version of the summarizer did the obvious thing: sent a fresh "you are a summarizer" system prompt followed by the conversation to condense. The system prompt sits at the very front of the request, exactly where the cache starts keying; one differing first token invalidates the entire prefix. Every compaction paid full processing price for the whole replayed history twice — once for the request that tripped the limit, once for the summary, at exactly the moment the history was longest. The fix is in the repo's own Agent Note (2026-07-21-compaction-summary-prefix-cache-reuse): the summarization directive moved from the front of the request to the end — the auxiliary call now reproduces the last routed request's prefix verbatim and appends one trailing instruction, making it a genuine prefix-extension of the warm request. Tools ride along on the summarization call even though the summarizer never calls one, because dropping them would misalign every following token.

The four presets: from training to self-modification

The video also surfaces the presets — the four agents "wearing the same skin" — which I verified in the shipped config files under apps/cli/config/agent-presets/: standard, PTC/code mode, minimal, and creation. Code mode replaces the tool list with a generated TypeScript interface over the tools plus one run_code transport: the model writes a program that loops, branches, and runs several reads at once, and only what it prints or returns comes back into the conversation — the model curates its own context instead of drowning in it. The reasoning is borrowed openly from Cloudflare: models have read millions of lines of real code and comparatively few tool-calling traces, so ask them for the thing they have actually seen. The program runs in a fresh worker thread with an empty environment, a heap cap, a wall-clock cap, and hard termination — containment, the video notes, not a security boundary, with authority comparable to the bash tool.

Minimal mode is the one worth pausing on. Two tools — a persistent shell whose working directory and environment survive between turns, plus str_replace_editor — and a system prompt of exactly one sentence: "You are a helpful software engineer assistant." The repo's own Agent Note (2026-08-10-minimal-preset-owns-rl-composition) says why: the minimal preset owns the complete Claude SWE-compatible RL agent composition, with the persistent bash environment the RL harness uses. The video's reading is direct: the minimal preset is a training environment shipped to you unchanged as an option in a dropdown beside the coding agent you are going to use anyway. The harness produces the trajectories; the trajectories feed post-training; the trained model goes back to work inside the same harness. DeepSeek open-sourced a piece of that loop, with the notes describing why each service in it belongs there.

Creation mode is the self-modifying preset this post's earlier section already examined through the cordis_* tools; the video adds the product framing — it sits in the same dropdown, its documentation says "treat a session on this preset as shell access," and its stated purpose is that a person can ask an agent to write another agent, and the preset that agent writes becomes something other sessions can mount.

The subagent backends and the memos

Both teardowns were stopped mid-scroll by the same feature: the subagent registry ships backends for Claude Code and Codex — not reimplementations, not scraped protocols. The Claude Code backend calls Anthropic's own agent kit at a pinned version, resolves the real Claude binary installed on your machine, and hands the kit that exact path; the Codex backend starts OpenAI's own app server over stdio and speaks its protocol. A DeepSeek agent running a DeepSeek model can hand a self-contained task to Claude Code, which works in the same directory, returns one answer, and is torn down — process tree and all, with the teardown proven before the call returns. The rejected-alternatives note explains why the shortcuts were refused: talking to the model directly or hand-writing the command-line protocol would bypass each product's official integration surface and prove nothing about approvals, tools, or cleanup.

And the memos — the number Cloud Codes dwells on: 683 English design records in .agents/notes/, plus a Chinese translation of every one, organized by status (proposed, implemented, rejected, archived), with every non-trivial change required to add or update a note in the same pull request, and every note required to carry an "alternatives considered" section. "A decision recorded without what it beat invites re-litigation." A script validates the headers, cross-checks the status against the folder, and rejects proposal language inside a note claiming to describe shipped reality; archived notes are frozen in an append-only manifest and must not be treated as authority. Cloud Codes' best evidence that this works is the postmortem of a web agent that was asked to change the interface it was itself running inside: it edited the source, started a dev server on a second port, validated that, then started a third server on a third port — three servers, one user, and the agent checking the only one nobody was looking at. The incident is readable in that detail because every step is traced by sequence number through the same append-only log the cache rule exists to protect. The design that keeps the bill down is the design that made the incident legible.

Same model, eight harnesses: the harness is the product

The second video starts with the numbers that motivated it: the same model ran thirty real work tasks through eight different harnesses — task success swung from 46.7% to 66.7%, and cost per finished task varied by a factor of seven. Nothing about the intelligence changed; what changed was the layer between you and the model. The video reports that the creator of the top-scoring harness read the DeepSeek repository and said it was the first time something new in this space made him want to revisit his own choices — when the winner reads a rival's homework and starts rethinking his own answers, the homework is worth reading.

Its four designs are the cache discipline, the event log, the one-row loop, and the process. The cache discipline: many frameworks write the current time into the top of the system prompt, so the prefix never matches and every request runs at full price forever; DeepSeek keeps the clock out of the prompt, sorts tool descriptions in one fixed order so nothing reshuffles, and runs a live test that flatly asserts every request after a session's first must hit the cache — "if any change breaks the prefix, the build goes red before the money burns." The event log: 44 kinds of events, exactly three visible to the model (user messages, assistant messages, tool results); the system never stores the conversation it sends — it recomputes the model's context from the log before every request, and a runtime check compares the outgoing request against what the log says it should be and refuses to send. The everyday superpower of that design is debugging: when an agent does something inexplicable, you stop guessing — replay the log to that step and the exact context the model saw is in front of you; crash at step 80, recompute and continue, same log, same context, as if nothing happened.

The one-row loop makes the everything-is-a-plugin claim legible in config: the loop that drives the agent — calls the model, runs tools, decides whether to continue — is one ordinary config rule, and disabled: true on that rule means there is no agent. The main loop and a tiny badge plugin are equals in the eyes of the config. Code mode is standard mode plus one appended rule; that rule alone flips how tools are presented to the model. The price of that flexibility is written in the repo's own incident reports: twice, a quiet configuration mistake silently broke the product; once, 178 green tests and a full coverage set on top of a system that died the moment a real editor connected. Their answer both times was a pre-release check that catches the class of mistake — there are 27 of those checks now. That is the bill for everything-is-a-plugin: pay it one crash at a time.

The process numbers are the fourth design and the thing that most surprised both teardowns: 12,293 commits in 64 days; the top contributor made about 5,000 of them; the branch names in the merge history count "worktree" 210 times and "codex" 209 times; there are more Markdown files in the repository than TypeScript files. The previous section's notes and checks are the mechanism behind those numbers — and the video sharpens the theory: this process is bureaucracy in a human team; in an agent team, it is guardrails, because the writer never gets tired.

Both videos end with the same honest caveats from DeepSeek's own known-limitations pages — the runaway-loop guard only sends reminders and eventually goes quiet, the file tools have no timeout at all, and early testers say daily experience still trails Claude Code and Codex. If you need work done this week, neither video recommends switching. And both end on the business model. Cloud Codes notes that on August 16, three days after the harness went free, DeepSeek's pricing page introduced peak and off-peak billing — uncached input goes from 43.5 cents to $1.32 at peak, output from 87 cents to $3.96: the harness gets cheaper and the tokens get dearer in the same week. The append-only design is what makes that survivable: a harness that keeps your prefix warm keeps most of your traffic in the cached column, at a fraction of the uncached price. Aaron's reading is the same shape: Anthropic keeps its harness closed and wired to a subscription — a moat around the model — while DeepSeek gives its harness away and it reads everyone else's files: a funnel for the thing they actually sell. And the side effect he names is worth keeping: when a vendor adopts its rivals' formats, your files become portable, whichever harness you run.

That last point connects to what this blog argued in Every Token Has a Price Tag: the unit got cheaper but the task did not, and the shape of the bill is a design decision. DeepSeek Harness makes the shape of the bill a first-class architecture property — the append-only log is not only a correctness design and an audit design; it is a billing design, worth roughly two orders of magnitude on the input side when the harness respects its own golden rule.

Reflecting: what the design buys, where it stops

The bet. Building the whole product on a plugin framework with reversible effects is a wager that harness engineering is, at bottom, a dynamic-composition problem: the hard parts of an agent runtime — adding capabilities, swapping providers, reloading policy, cleaning up after a failed experiment — are the hard parts of runtime plugin management. The wager is coherent, and the evidence base is not trivial: the framework underneath shipped in Koishi with 4,000+ community plugins before the theory was written down. The paper's own conclusion is the honest version of the story: the theory was extracted from a working system, not written first and applied later. What the formalization buys is the second product — dsh did not have to re-solve plugin lifecycle, HMR, dependency resolution, or teardown; it inherited them as a vendored, formalized substrate and spent its own complexity budget on agent concerns: the session log, the seams, the pipeline, the policy. That is exactly the economics this blog keeps returning to in harness-engineering-best-practices-for-ai-agents and go-is-good-for-harness-pipelines: the harness is where composition complexity concentrates, and the team that treats composition as the product wins the cost curve.

The harness is the product. Both teardowns end on the sentence this blog has been circling for months, and the numbers are finally there to back it: the harness is the product. Cloud Codes reads the public Terminal-Bench board the same way — the same weights score 83.8% under one major harness and 80.4% under another, 3.4 points decided entirely by software with no weights in it — and Aaron's own benchmark found the same model finishing between 47% and 67% of real tasks across eight harnesses while cost per finished task varied sevenfold. No weights changed in any of those comparisons. The wrapper changed. The comparison research in the insights above makes the point stronger, not weaker: SWE-agent's ACI paper argued the interface is the lever; Meta-Harness reached 76.4% on Terminal-Bench 2.0 and was itself found by automated harness evolution; terminal-bench-rl reports that harness-level improvements lifted a Qwen3 agent to the top of its class without training. That is why a lab publishing its harness under an MIT license is giving away something much closer to the product than the announcement suggests: the harness is not the part with the intelligence, and it is the part with the leverage.

The guarantees stop where the paper's do. Observational equivalence, not literal restoration — unplugging a component does not restore the heap's exact layout, only what the declared dependencies observe. The sandbox vocabulary covers file effects only; network and process visibility are out of scope by declaration. The self-modification toolset is bash-equivalent trust, explicitly not a security boundary. And the deeper caveat survives from the paper: recovery guarantees clean removal, and for agents the interesting failure is the one where a faulty self-modification disables the very process needed to recover — the calculus makes removal safe, but removal still has to be invoked.

The training loop is the product, too. The minimal preset is the sharpest thing either teardown found, and it deserves its own reflection. The harness DeepSeek hands you for free is the same environment its models are trained in: a two-tool, one-sentence-prompt composition whose Agent Note names its purpose outright — the Claude SWE-compatible RL agent. The harness produces the trajectories; the trajectories feed post-training; the trained model goes back to work inside the same harness. That closes a loop most labs keep private, and it is the strongest form of this blog's agent-harnesses-need-tasks-that-fight-back claim: the tasks a harness runs are not only an evaluation, they are the curriculum. It is also why "everything is a plugin" is not a design aesthetic but a training-infrastructure decision: the row that defines the training environment is the same row you can edit in the shipped product. And the reversible-effects guarantees matter beyond the product for the same reason: a training run is millions of agent steps, and the promise that teardown fully undoes what a component did is what keeps one experiment's state from leaking into the next run's trajectories. Cloud Codes ends with the question the loop raises: "The model is learning your harness. Is your harness learning anything back?" The honest answer, as with every guarantee in this post, is that the loop optimizes whoever runs it — which is why the same week the harness goes free, the tokens get dearer.

The preview caveat. More than 149,000 stars in four days is a demand signal, not a validation of production readiness. The README's first declaration is "developer preview... THERE WILL BE COMPATIBILITY-BREAKING CHANGES." The session log carries SESSION_FORMAT_VERSION at 0 with no compatibility promise; backends reject old on-disk formats. The release cadence is remarkable — 0.1.0-rc.7 and 2,600+ merged PRs by day four — but that velocity is exactly the argument for treating the docs as the product's present shape and the code as a moving target. The single-process runtime is another boundary worth naming: everything runs in one shared process, so the compositional guarantees are process-internal; cross-process isolation is delegated to the sandbox providers and the subagent seams, which is where the real blast-radius questions live.

The bet with a deadline. Cloud Codes ends by making the sharpest claim in either video falsifiable: within a year, at least two of the major harnesses — Claude Code, Codex, Cursor's CLI, Gemini's, Aider, the LangChain stack — will publicly document an append-only or prefix-preserving history model. If the bet holds, the append-only log stops being DeepSeek's signature and becomes the industry baseline, and this post's cache arithmetic stops being a curiosity and becomes the reason every harness documents its history discipline. If it fails, the repository's discipline was an outlier, not a direction — and the difference will be visible in the same place the videos looked: the bill.

What to steal regardless. The session log as single source of truth with a logged-surface invariant; the seam discipline (definition / provider / consumer, one role is not a capability); the tool pipeline as a waterfall of policy with monotonic guards for final denial; the docs-as-machine-checked-artifact practice with freshness-gated generated catalogs; the defensive-patterns page as a bug-class ledger; the honest scope declarations (file effects only, bash-equivalent trust, per-call policy). The teardowns add two more items to the list. First, the cache trio: keep the clock and anything else volatile out of the prompt prefix, sort tool descriptions in a fixed order, and run one test that asserts cache hits — the bill is the assertion. Second, the rejected-folder discipline: a decision recorded without what it beat invites re-litigation, so make "alternatives considered" a gate, not a habit. Any harness team can adopt any one of these without adopting Cordis.

The project's most distinctive move — and the reason this blog's earlier spatiotemporal-composability coverage connects to it directly — is that it makes the plugin runtime itself the product surface: dump-config prints your machine's tree, any row is replaceable by a patch, and the agent that runs inside the tree can inspect, mount, and unmount its own components. Four days after the calculus appeared on arXiv-style GitHub, it was the shipping substrate of a ~150,000-star harness. The theory mattered; the harness is what the community voted for — and the community's own teardowns of it are already teaching the rest of the industry which parts of the architecture are portable and which are the product.

References

• DeepSeek Harness documentation (English) — https://deepseek-harness.github.io/deepseek-harness/en/
• DeepSeek Harness repository — https://github.com/deepseek-ai/deepseek-harness
• README.md — "Everything is a Plugin", powered by Cordis
• docs/architecture.md — profiles, bundles, the turn flow, capability seams
• docs/cordis-primer.md — Cordis in five ideas; dispatch modes; waterfall semantics
• docs/agent-lifecycle.md — turn and step sequence diagram
• docs/tool-execution-pipeline.md — the guarded pipeline
• docs/defensive-patterns.md — the bug-class ledger
• docs/AGENTS.md and AGENTS.md — documentation tiers, standing orders
• Subsystem pages: session, scope, tools, shell, sandbox, approval, permission-presets, compaction, skills, subagent, workflow, commands, goal, schedule, plan, invariants, session-telemetry
• Agent Notes: microkernel event taxonomy (2026-06-11), capability seams (2026-06-13), code mode (2026-06-15), reconstructable requests (2026-07-05), agent-scope runtime design (2026-07-12), canonical tool output (2026-07-20), compaction prefix-cache reuse (2026-07-21), per-session agent presets (2026-08-03), minimal preset owns the RL composition (2026-08-10)
• .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md — the cordis_* toolset design
• docs/user/guide/python-sdk.md — deepseek-harness-sdk, bundled runtime
• A Programming Paradigm for Spatiotemporal Composability (Shi, Zhang, Cui; PKU + DeepSeek-AI) — https://github.com/cordiverse/paper
• This blog's coverage of that paper — Spatiotemporal Composability: The Missing Calculus for Self-Evolving Agents

Other harnesses referenced in this post

• OpenHands — https://github.com/All-Hands-AI/OpenHands — event-stream backbone, replay and event search
• MiniCode — https://github.com/FuSC24/MiniCode — the LLMClient reference shape behind reconstructable requests
• SWE-agent — https://github.com/SWE-agent/SWE-agent — "Agent-Computer Interfaces Enable Automated Software Engineering" (Yang, Jimenez, et al.)
• Claude Code — https://code.claude.com/docs/en/hooks — hook matcher groups, permissions; the protocol DeepSeek bridges
• Codex — OpenAI's agent CLI; DeepSeek's subagent backend starts its app server over stdio
• Aider — https://github.com/Aider-AI/aider — git as history, repo map
• Cloudflare Code Mode — https://blog.cloudflare.com/code-mode/ — the cited antecedent for code mode
• Harbor / Terminal-Bench — https://github.com/harbor-framework/terminal-bench — the Terminus-2 harness family
• Terminus-KIRA (KRAFTON AI) — https://github.com/krafton-ai/KIRA — harness-level improvements on Terminus 2
• Meta-Harness (Stanford IRIS) — https://github.com/stanford-iris-lab/meta-harness-tbench2-artifact — 76.4% on Terminal-Bench 2.0, found by automated harness evolution
• Terminal-Bench-RL — https://github.com/Danau5tin/terminal-bench-rl — GRPO training of terminal agents at 32×H100
• Gemini CLI — https://github.com/google-gemini/gemini-cli — conversation checkpointing, GEMINI.md context files, MCP
• Claude Code checkpoints — https://code.claude.com/docs/en/checkpoints — git-based working-tree rollback
• OpenHands event service — https://github.com/All-Hands-AI/OpenHands — event history search and confirmation API
• LangGraph — https://github.com/langchain-ai/langgraph — the loop as an explicit graph
• Typert — packages/typert in the DeepSeek Harness repo — the compiler-independent type-graph analyzer behind RPC contracts, tool catalogs, and the agent-visible API catalog
• packages/hooks/hooks-claude-code — the real-hooks.json bridge
• packages/compaction/compaction-basic/src/summarizer.ts — the Claude-shaped eight-section checkpoint
• packages/workflow/workflow-worker-thread — model-written orchestration scripts in a vm realm
• packages/sandbox/sandbox-local — the bwrap → Landlock → Seatbelt → Windows-ACL confinement chain with functional probing

Videos

• Cloud Codes. DeepSeek Harness Architecture: Insane Software Engineering Behind It (2026-08-15, 21:27) — the append-only golden rule, the ~120x prefix-cache discount, the invariant module that disbelieves the loop, the compaction-prompt fix, the four presets, and the 683 agent notes.
• Aaron — AI-native builder. What I Learned From DeepSeek's Harness (2026-08-16, 10:06) — the eight-harness benchmark (47%–67% success, 7x cost), the 44/3 event log, the one-row agent loop, and the agent-built process behind 12,293 commits.