The DeepSeek Harness Handbook

Chapter 1What you just joined

DeepSeek Harness — dsh on the command line — is an agent harness. That is the software that sits between a large language model and the real world: it builds the prompt, calls the model, streams back the answer, runs the tools the model asks for (reading files, running shell commands, searching the web), records everything that happened, and renders it for a human. The model supplies the thinking. The harness supplies everything else — and "everything else" is a surprisingly large amount of software.

Most harnesses are one program with extension points bolted on. This one inverts that. There is no core program. There is a small plugin framework, and then every single feature is a plugin — the model adapter, the tool registry, the conversation log, the permission system, the web interface, and even the main agent loop itself. What ships as "the product" is a list of 78 configuration rows saying which plugins to load.

That is the one idea you need to hold onto. Everything in this handbook is a consequence of it.

Who builds it

A small team inside DeepSeek — 28 people appear in the commit history available to this report, with roughly 8–10 committing regularly. Chapter 11 breaks down who works where.

One thing to know up front, from CONTRIBUTING.md: the project does not accept external pull requests right now. It is open source, and the team actively wants an ecosystem, but they want that ecosystem to live in other people's plugin repositories rather than in this tree. The document says so directly:

DeepSeek Harness is designed to be deeply customizable. We do not believe that packages in the official repository are inherently more important than packages created by the community. You may consider this repository an idea, an official showcase, and a source of inspiration, but not a mandate from us.

CONTRIBUTING.md

This matters for you practically: the plugin interfaces are treated as public API even though the version number starts with a zero. When you design something, assume a stranger will build on it.

What state the project is in

Version 0.1.0-rc.5, published to npm, pre-1.0. The root AGENTS.md opens with a section that will not survive the first real release:

Pre-release stance: foundation over blast radius. With no external consumers, prefer the correct foundation over compatibility shims: rename or repackage freely and update every reference together.

AGENTS.md

Take that literally. In the few weeks of history this report can see, whole package groups were renamed — bash/ became shell/, self-modification/ became extensions/, support/ became test-support/. If you find a document or a memory that references an old path, the path moved and nobody left a redirect. That is deliberate.

Chapter 2Day one: make it run

Before reading any more architecture, get the thing running. The mental model lands much faster when you have watched it work.

Prerequisites

• Node ^22.19.0 || >=24.0.0 — older majors are not supported.
• pnpm — this is a pnpm workspace; npm and yarn will not resolve it correctly.
• A DEEPSEEK_API_KEY in a root .env file, for anything that talks to a real model. Everything else runs without one.

# install the whole workspace
pnpm install

# run one task through the one-shot runner (needs a key)
pnpm dsh --profile headless "list the files in this directory"

# see the plugin tree your machine actually boots — no key needed
pnpm dsh --profile web --dump-config

# the demos
pnpm run demo:acp      # automation server over the Agent Client Protocol
pnpm run demo:cordis   # the agent modifies its own running plugin tree

Then the checks. Do not run the whole suite — see Chapter 13 for why, and for how to choose. For now, just confirm the basics work:

pnpm run typecheck      # tsc across every package
pnpm run lint           # oxlint
pnpm run test           # vitest unit tests
pnpm run build          # tsc emits lib/types, tsdown bundles runtime

Chapter 3The map of the repo

Nine top-level directories. Here is what each one is for.

Inside packages/, the 49 groups are not arbitrary. Each one is a capability family — the definition of a capability plus its implementations plus the model-facing tool that uses it. Learn these ten first; the rest follow the same pattern.

Every group has a README.md listing its packages and their service keys, and packages/README.md indexes all of them. That file is the fastest way to find where something lives.

Chapter 4Everything is a plugin

The framework underneath is Cordis. It lives in vendor/ as pinned source rather than as an npm dependency, because the team modifies it and refuses to have a version-skew problem in the thing that boots the product.

Cordis has five ideas. Learn them and 80% of the repo becomes readable.

1. A plugin is an object

Either a plain object with an apply(ctx) function, or a class extending Service. That is the whole definition.

2. A context is a repository of services

A service claims a stable key — ctx.tools, ctx.llm, ctx.sessions — and everyone else finds it by key, never by importing the implementation. This is why a provider can be swapped without touching its consumers.

3. Dependencies are declared, not ordered

A plugin lists what it needs in inject and Cordis waits until those services exist. Nobody maintains a boot sequence.

4. Events are typed, and their dispatch mode is part of the contract

Four modes: emit (fire and forget), waterfall (middleware that can transform or short-circuit), parallel, and serial. Plugins add their own event types by TypeScript declaration merging, without editing the package that owns the event.

5. Registrations are reversible effects

Everything you contribute — a tool, a prompt section, an adapter, a listener — is installed through ctx.effect() or ctx.on(), which return a disposer. Unload the plugin and every contribution unwinds automatically.

What a plugin actually looks like

Here is a complete, working plugin — a tool the model can call. This is taken from the tool cookbook and it is genuinely all the code required:

import { readFile } from 'node:fs/promises'
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'my-tool'
export const inject = ['tools']              // wait for ctx.tools to exist

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'read_file',
    description: 'Read a file from disk.',      // what the MODEL sees
    parameters: {
      path:  { type: 'string', required: true, description: 'Absolute path' },
      limit: { type: 'number' },                  // optional by default
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args, exec) {
      // args is TYPED from the schema above: { path: string; limit?: number }
      // and already validated — you do not parse model JSON by hand
      return readFile(args.path, { encoding: 'utf8', signal: exec.signal })
    },
  }))
}

Read that again with the five ideas in mind. inject declares the dependency. ctx.tools is found by key. register() returns a disposer, so disposing this plugin's fiber unregisters the tool. And the schema flows into system-prompt assembly automatically — nobody wires it up.

Chapter 5How the app is assembled

There is no main() that wires the product together. Instead there is a YAML file listing plugins. Here is a real fragment from the one-shot runner in examples/headless-agent:

# User-settings document ($DSH_HOME/settings.yaml, hot-reloaded)
- id: settings
  name: '@deepseek-ai/dsh-settings-file'

# Credential store: live process env over $DSH_HOME/.credentials.yaml
- id: credentials
  name: '@deepseek-ai/dsh-credentials-local'

# The DeepSeek adapter. Swap to dsh-llm-pi-ai for the pi-ai-backed twin.
- id: llm-deepseek
  name: '@deepseek-ai/dsh-llm-deepseek'
  config:
    thinking: enabled
    reasoningEffort: max
    models:
      - id: deepseek-v4-pro
        contextWindow: 128000

- id: subprocess
  name: '@deepseek-ai/dsh-subprocess-local'

- id: bash
  name: '@deepseek-ai/dsh-bash-local'

Each row has an id (a stable handle), a name (the npm package), and optional config. Row order carries no meaning — activation is driven by service availability, i.e. by inject.

Profiles, bundles, and patches

Real deployments do not hand-write the full list. They stack layers:

The command you will use constantly:

pnpm dsh --profile web --dump-config

When something is not loading, this is the first thing to run. It shows you the resolved tree, so you can see whether your plugin is even in it before you start debugging why it is not working.

Chapter 6The loop, step by step

Now the part everyone wants to understand: what actually happens when a user sends a message. The driver lives in packages/core/agent-loop/src/agent.ts and it is about 1,600 lines including its siblings — small, because all the policy lives in plugins.

The vocabulary (get this right)

A turn with zero steps is not a bug. If a hook rejects the input, the turn still opens and closes so the log records that something was attempted and blocked.

The inbox: two lanes and a wakeup bit

Input does not go straight to the model. It goes into the agent's inbox, which holds two ordered lists. There is one primitive:

send(message: UserMessage, target: 'next-turn' | 'next-step', wakeup: boolean)

and three named presets over it that you will see everywhere:

That third row is the one people miss. inject() on an idle agent does nothing visible — the context sits in the inbox until something else wakes the driver. That is intentional, and it is the right behaviour for things like "the file you were editing changed on disk."

The inbox is also durable: every mutation is recorded as an agent/inbox/spliced event, so pending work survives a reload and the UI rebuilds the queue from the log rather than from memory.

One turn, end to end

Here is the actual code for the inner part of a step, lightly trimmed. Notice how little it does:

const stream = preparedCall?.stream(request) ?? this.loopCtx.llm.stream(request)

for await (const chunk of stream) {
  signal.throwIfAborted()
  // every chunk is appended to the durable log AS IT ARRIVES
  chunkSeqs.push(this.session.append('assistant/chunk', { turn, step, chunk }).seq)
  assembler.push(chunk)
}

const finish = assembler.finish
if (finish.kind === 'error' || finish.kind === 'aborted') {
  // the loop does NOT know how to retry. it asks.
  const action = await this.dispatch.waterfall('agent/request-error', { … })
  if (action?.kind !== 'retry') throw new LlmError(…)
  continue   // a listener said retry — go around again
}

Chapter 7The log you must not break

If you remember one technical thing from this handbook, make it this one.

A session is an append-only log of typed events. The conversation history sent to the model is not stored anywhere — it is derived from the log every time, by folding a pure function over it.

The projection rule is one pure function, and its JSDoc explains why it must stay pure:

/**
 * Project a single event into the LLM message it derives to, or null when it
 * produces none … This is THE per-node projection rule: `Session.deriveMessages`
 * folds it over the live surface, external reconstructors and pure projections
 * fold the same function over a log prefix's surface to rebuild the exact
 * messages any request was built from.
 */
export function deriveEventMessage(event: SessionEvent): Message | null {
  switch (event.type) {
    case 'user/message':      return event.data
    case 'assistant/message': return event.data.message.content.length === 0
                                    ? null            // empty = usage-only, skip
                                    : event.data.message
    case 'tool/result':       return event.data.message
    default:                   return null   // boundaries, chunks: trace data
  }
}

One more strictness you should expect: reading is fail-closed. A build that encounters an event type it does not know refuses the log, unless the event was explicitly marked ignorable: true by its producer. That feels harsh until you realise the alternative is silently showing a user a different conversation than the model actually saw.

Chapter 8Tools

Tools are how the model does anything at all. There are 52 of them shipped across 24 packages — bash, read, write, edit, grep, glob, web_search, todo_write, subagent, terminal_*, session_*, and more. The full generated list is in docs/tool-catalog.md.

You saw the minimal shape in Chapter 4. What you did not see is everything the registry does around your execute() function.

Three things about this that are easy to get wrong

Guards are not the same as the pre-execute waterfall. A waterfall runs listeners in registration order, and registration order depends on composition — which a user can change with a patch. That is fine for annotation and unacceptable for security. So there is a second layer: guards, which can only deny or abstain, never allow. Because they cannot allow, their order cannot change the outcome. If you are writing policy that must hold, write a guard.

Only three fields ever reach the model. When the registry builds tool schemas for a request it uses an explicit allowlist: name, description, parameters. Your timeoutMs, isConcurrencySafe, output schema, and UI presenters are internal and must never leak into a prompt.

Presenters must be pure. presentCall(args) and presentResult(args, result) decide how your tool renders as a card in the UI. They run during live streaming and during log replay, so they may do no I/O, read no session state, and use no clock or randomness. If you find yourself wanting the file's previous contents inside presentCall, stop — that belongs in durable result metadata.

Chapter 9Capability seams

When the team says "add a capability," they mean a specific three-part structure. Getting this vocabulary right will make code review go much better.

There are 55 service keys in the system. Here are the ones you will meet first:

Chapter 10The rest of the system

You do not need these on day one, but you should know they exist and roughly where they live, so you recognise the names in review and in the event matrix.

Chapter 11Who works on what

By area — who to ask

By person — what each has been building

Two things the data tells you about how this team works

Everyone writes Agent Notes. .agents/notes/ is the single most-touched directory in the repository — 249 focused commits from 18 different people, ahead of every package and ahead of docs/. For nine of the top eleven contributors it is their #1 or #2 area. Design records are not bureaucracy layered on top of the work here; they are a large part of the work. Budget time for yours.

The front end is the busiest part of the product. packages/client plus apps/web is 286 focused commits, more than twice the core spine, docs, or scripts. If you are joining to work on "the agent," be aware that most day-to-day motion is in the browser half — and that the browser half is built out of the same plugin machinery as everything else.

git log --no-merges --format='%an' -- packages/<the-thing-you-touched> | sort | uniq -c | sort -rn | head

Chapter 12Your first change

A good first task is adding a tool, because it exercises nearly every convention in the repo without requiring you to understand the loop deeply. The guided version is docs/user/develop/basic/tool.md; the contract reference is docs/cookbook/adding-a-tool.md.

Here is the full checklist of what a non-trivial change ships. Missing items are the most common reason a review stalls.

An ./invariant companion is smaller than it sounds. Here is a real one, from tool-todo, checking that every todo snapshot reaching the durable log is well-formed:

const PACKAGE_NAME = '@deepseek-ai/dsh-tool-todo'
export const name = 'tool-todo-invariant'
export const inject = ['invariants']

function validateTodos(value: unknown, fail: InvariantFailure): void {
  if (!Array.isArray(value)) fail('todo/write todos must be an array')
  const seen = new Set<string>()
  for (const item of value) {
    const { content, status } = item as Record<string, unknown>
    if (seen.has(content)) fail(`todo/write repeats content …`)
    if (!TODO_STATUSES.has(status)) fail(`todo/write carries unknown status …`)
  }
}

export const apply = (ctx: Context) =>
  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

Note what its JSDoc says it deliberately does not check — how many todos are in_progress — because that is per-deployment config, and "a log written while parallel work was allowed must still replay after a deployment tightens the policy." That is the level of care expected in these files.

Branching and pull requests

• Develop on a branch; open a PR against master.
• Fill in the PR template.
• Labels: exactly one kind/*, every material area/*, plus a native Issue Type.
• Split independent changes into separate PRs. If a change builds on another, use GitHub's official stacked-PR feature rather than hand-managed bases.
• Rewrites use --force-with-lease, never raw --force.

Chapter 13The gates

There are 124 scripts in scripts/ and a lot of them can fail your PR. The important thing to internalise first is which ones to run locally.

Gates that surprise newcomers

• Per-file 100% coverage. Read an uncovered line as a question: is this code dead? The policy says outright that an uncovered line "is often dead code the gate is correctly flagging for deletion, not a missing test to bolt on."
• Documentation word budgets that ratchet down over time. Raising a ceiling requires justification in the PR.
• Bilingual pairing. Docs exist in English and Chinese with a paired .i18n.yaml. A gate checks they stay in sync.
• Type blocks in docs are verified against source. A ts type-equiv fence in a Markdown file is checked against the real type — so documentation cannot drift silently.
• Generated catalogs must be fresh. The module graph, event matrix, capability-seam graph, config catalog, tool catalog, and persistence catalog are generated and CI verifies you regenerated them.
• One trailing newline per file, enforced by a pre-commit hook.

Chapter 14Rules that will bite you

These are the conventions from AGENTS.md and packages/AGENTS.md that are non-obvious. Each one exists because something went wrong once.

Waterfall listeners must call next()

A waterfall is around-middleware. Returning without calling next() short-circuits the whole chain — every listener after you never runs. That is a legitimate design for a listener that owns a decision, and a bug for one that only annotates. Know which you are writing.

Use ctx.get(name) for optional services

Reserve ctx.<name> for services you declared in inject. The property proxy is topology-sensitive; ctx.get reads the global service store. Mixing them up produces "service is undefined" in one composition and not another.

Enforce a decision where it is made

Leaving a tool out of the prompt is not enforcement. Neither is a facade, a wrapper, or listener order — anything a direct caller can bypass. Test denial through the executor. The corollary is that a filtered-away tool must be indistinguishable from a nonexistent one.

No hardcoded tunables in plugins

Anything that varies by deployment is a validated Config field settable from cordis.yml. A DEFAULT_* constant or a test hook does not count as configurability. Protocol constants, external specifications, and security invariants stay fixed.

Explicit beats implicit at package boundaries

Defaulting is an explicit resolve(request): Spec step in the owning implementation, never a hidden ?? default buried in run(). The shell request/spec split is the template.

Misconfiguration fails loud

At load when self-contained, otherwise at the earliest resolvable point. Never silently skip a missing referent.

An empty catch must name what it swallows

…and why nothing else can reach it. Keep the try to a single statement.

Branded IDs, not bare strings

Opaque IDs that cross package boundaries use Branded<B>, so a SessionId cannot be passed where a CallId is expected. Structurally they are strings; at the type level they are not interchangeable.

Trust TypeScript at typed same-process boundaries

Do not add runtime validation or hostile-input tests for values the static interface already guarantees. Validate at the real boundaries: parsers, config, queues, model and tool JSON, files, workers, processes, and the wire. Defensive code everywhere is treated as noise here.

Write prose like a contract, not a transcript

This one catches almost everyone. Comments and docs state complete contracts and current behaviour — never reasoning narration. No "this used to…", no "a later PR will…", no restating what the code plainly does, no review history. Use direct, concrete terms; the standard explicitly asks you to write response fields rather than response shape, and to reserve the word contract for actual preconditions and guarantees. There is a skill, dsh-trim-cot-leakage, that exists purely to audit for this.

Chapter 15Where to look things up

Much of this repo's reference material is generated from source and verified fresh in CI. When you need a fact, prefer these over grepping.

That last row is worth a habit. The expensive question in a mature codebase is never "how does this work" — it is "why isn't it the obvious other way." The rejected notes answer that directly, and reading a few of them will teach you this team's taste faster than anything else.

↑ Back to top