deepseek-harness: an independent review

Written 2026-08-13 against upstream HEAD 47f943859b (v0.1.0-rc.5). This is a study clone; all commits stay local. Every claim below carries a file:line reference and, where it matters, a quoted snippet — verify against current code before relying on any of it, because upstream promises breaking changes.

What this review is

A from-scratch, warts-and-all audit of DeepSeek's agent harness (dsh). Three goals: demystify how the thing actually works, explain the designs and why they are shaped that way, and surface every strength and weakness the evidence supports. It was produced by six parallel code audits (core runtime, capability surface, surfaces/distribution, process/quality, upstream's own docs, and the .agents/ tree), then synthesized by hand. It replaces an earlier review that was discarded without being consulted.

The headline

The most interesting fact about this repository is not the product. It is how the product is built. The repo is 64 days old (first commit 2026-06-10, "Initialize repo with README, AGENTS.md, and CLAUDE.md symlink"). In those 64 days: 12,294 commits, ~2,500 internal PRs (~39 per day), ~20 human contributors — with 203 codex/* and 306 worktree/* branch merges, a standing rule that every non-trivial change must ship an "Agent Note" decision record in the same PR (AGENTS.md:122), and an in-repo skill whose whole job is scrubbing their own model's chain-of-thought leakage out of committed prose (.agents/skills/dsh-trim-cot-leakage/SKILL.md). dsh is as much a demonstration of large-scale agent-driven software development as it is an agent harness. Reading it teaches you two things at once: how they designed a harness, and how a small team runs a 219-package monorepo at 39 PRs/day with agents doing most of the typing.

One-screen verdict

The architecture claim is real. "Everything is a plugin" is not marketing: the agent loop itself is a config row (packages/bundle/base/cordis.patch.yml:436-437), and the session event log is a genuine single source of truth with a test-mounted invariant that fails the run if an LLM request ever diverges from the log-derived state (packages/core/agent-loop/src/invariant.ts:39-42, mounted via vitest.config.ts:120).
The security model is one boundary doing all the work. A kernel-level file sandbox (bwrap/Landlock/Seatbelt/Windows-ACL) is the only real enforcement. There is no command-level permission gate on the shell tool (the code says so itself: packages/shell/tool-bash/src/index.ts:6), no authentication on the web surface (loopback-only by construction instead), and run_code executes outside the sandbox entirely. The code is unusually honest about all of this.
The process machinery is world-class and has a blind spot. ~30 documentation gates, 100%-per-file coverage thresholds, publish verification that installs every tarball into a clean consumer. Yet the doc-drift we found clusters inside generated and gated docs: the gates verify freshness-of-generation, not truth-of-generator.
It is a developer preview and behaves like one. Eight release commits in one day, a version line reset mid-flight, a tui profile advertised in --help that does not exist in the box, and a formal statement that no compatibility is promised (AGENTS.md:7, SESSION_FORMAT_VERSION = 0).

How to read this review

File	What it answers
what-is-dsh.html	What is this, what actually ships, what happens when you run `dsh web`, where state lives on disk.
architecture.html	The plugin model, the turn loop end to end, the session log, scopes, host/client split — and the tradeoffs of each.
capabilities-and-security.html	Tools, seams, the sandbox, permissions — what is enforced and what is advisory. MCP, skills, subagents, hooks, workflows.
how-they-build-it.html	Velocity, agent-driven development, the `.agents/` tree, Agent Notes, the bilingual doc pipeline, testing, CI, releases.
strengths.html	The ranked list of things worth stealing.
weaknesses.html	The ranked list of warts, each with evidence.
verdict.html	Adopt or not; what to copy; open risks.

Number conventions used throughout

Upstream HEAD is 47f943859b (2026-08-13); the study clone adds local commits on top.
"219 packages" means directories matching packages/*/*. The npm publish family ("dsh") is 221 (those plus apps/cli and apps/web). Workspace-root counts (for example in dependency-cycle analysis) are 74.
.agents/ counts: 686 English source documents, which the bilingual pipeline expands to 2,078 tracked files (each note is an English .md, a Chinese .zh.md, and a hash-record .i18n.yaml).