DeepSeek Harness CLI

August 26, 2026 · View on GitHub

An unofficial terminal-native console for DeepSeek Harness.

Status: M7 public alpha (0.1.0-alpha.10), delivering the protocol-independent M7.0–M7.3 slices plus the M7.4 compatibility gate and M7.6 hardening. The coding baseline includes composition patches, vision, web research, MCP bridging, restricted self-service Harness plugin installation and a trusted Cordis development mode. The full Harness dependency closure and compatibility gate are pinned to 0.1.1-rc.2; authoritative runtime inspection and interactive approval answering remain gated on an upstream extension contract.

简体中文 · Install · Compatibility · Plugin Workbench · M7 history/context/permissions · Demo · Changelog · Extensions · Design · Protocol · Development · Roadmap

Install the public alpha

npm install --global @liaosiyuan123/dshc@alpha
dshc doctor
cd /path/to/repository
dshc

The npm package is @liaosiyuan123/dshc; the installed command is dshc. The unscoped packages dshc and deepseek-harness-cli are not published by this repository. See installation and lifecycle for provider configuration, pinning, update, uninstall and diagnostics.

The idea

DeepSeek Harness is a plugin-first agent runtime. dshc is its terminal control plane, not a second agent harness.

Harness owns agent semantics; dshc owns terminal interaction, projection, observability and presentation.

dshc uses the official Harness SDK/runtime boundary and keeps models, tools, skills, approval, sandboxing, persistence, sessions, subagents and the agent loop upstream-owned.

What works now

The M4 default path is a Harness-native coding runtime rather than the old minimal demo composition:

cd repository
 -> dshc
 -> Harness filesystem / search / platform shell / subagents / todo
 -> workspace-write sandbox + never approval policy
 -> Ink terminal product / plain compatibility paths
 -> bounded local transcript + trace retention
 -> clean runtime teardown

Current capabilities:

  • Ink 7 + React 19 structured TTY product on the Node 22.19/24 baseline;
  • persistent multi-turn conversation with one Harness runtime and stable active session;
  • zero-config repository cwd workflow with Harness-owned read, write, edit, glob, grep, Bash on POSIX / PowerShell on Windows, subagents and todo state;
  • shared upstream workspace-write sandbox policy for filesystem and shell writes; danger-full-access is never an implicit fallback;
  • upstream approval policy is never; protocol 0.0.1 has no dshc server-to-client approval transport, so the model is not promised an unavailable escalation path;
  • vision routes image inspection to deepseek-v4-flash-vision-exp; web_search, web_fetch and the read-only researcher role use Harness-owned seams and timeout policy;
  • workspace MCP servers can be enabled by patch; calls retain mcp__<server>__<tool> provenance in /tools and activity views;
  • resize-aware transcript, grapheme-safe prompt editor, history navigation and adaptive status line;
  • /help, /status, /session, /new, /clear, /plugins, /capabilities, /trace, /agents, /exit;
  • a slash menu built from the live registry: arrows choose, Tab completes, Enter runs a finished command and completes an unfinished one, and the window scrolls instead of stopping at the fold;
  • assistant prose is presented as safe terminal text; a best-effort local legacy formatter remains isolated from tool output, but the deployment persona tells the model that this surface cannot reliably render Markdown and requires plain-text responses;
  • active-turn Ctrl+C performs an honest hard interrupt: it stops the whole Harness runtime, starts the same configuration again and selects a fresh session because protocol 0.0.1 cannot cancel or resume the interrupted one;
  • a token usage readout in the status line and /status, in absolute numbers: upstream reports no context window on this transport, so dshc reports no percentage;
  • first-party terminal plugin API v1 with deterministic command, renderer, view and status registries;
  • specialized coding-tool/subagent presentation plus a safe generic event fallback;
  • bounded activity/trace/transcript/topology diagnostic retention with explicit eviction disclosure;
  • terminal ESC/CSI/OSC/C1/bidi sanitization, secret-redacted diagnostics and exception-safe alternate-screen cleanup;
  • dshc doctor compatibility/startup preflight that performs initialize only and never issues a model prompt;
  • trusted dshc --dev for interactive host-only Cordis prototypes, with an always-visible process-authority warning, official lifecycle tools only, /workbench observation and no dshc-owned runner;
  • dshc doctor --dev checks exact Cordis packages, developer patch order and initialize without credentials or dynamic execution;
  • read-only /history browsing over Harness-owned JSONL artifacts, scoped to the current workspace by default, plus review-first Ask History into a fresh session;
  • /context, /prompt and /permissions distinguish observed runtime facts, requested local projections and capability gaps without inventing a context window, final Prompt or approval answerer;
  • Windows workspace-local TEMP/TMP is diagnosed both by doctor and before interactive startup; dshc explains why every pwsh/shell call fails without relocating TEMP or weakening the sandbox;
  • M1/M2 one-shot, piped stdin, JSON and scripted non-TTY --interactive modes retained.
  • a deployment persona built from the launch itself — host, workspace, proxy and registry configuration, plus client-only facts about fail-closed approval, hard-interrupt semantics and the plain-text-only output target (DSH_SYSTEM_PROMPT replaces it wholesale);
  • the shipped composition remains authoritative; <workspace>/.dshc/cordis.patch.yml is the only automatic workspace layer, and /config separates base, patch and effective requested configuration;
  • scout / planner / reviewer / oracle read-only role subagents alongside the general subagent, mounted on the upstream delegation seam rather than on a scheduler of our own — see subagent roles;
  • /config, /config fork, /model, /provider and /reload for inspecting and patching composition, each stating the session loss before it acts;
  • /plugin search and /plugin install for @deepseek-ai/ packages only, with exact named confirmation, immutable candidate profiles, private-patch trial initialization and atomic workspace-patch promotion only after success.

Source usage

corepack enable
corepack prepare pnpm@11.7.0 --activate
pnpm install --frozen-lockfile

# Preflight is safe before a provider key exists: it reports credential presence only.
pnpm dev -- doctor
pnpm dev -- doctor --json

# Configure the normal DeepSeek Harness provider environment for model-backed work.
# No positional prompt in a TTY => terminal product.
pnpm dev

# Trusted Cordis package development (interactive TTY only).
pnpm dev -- doctor --dev
pnpm dev -- --dev

Inside the TTY product:

/help          capability-aware command help
/status        runtime/model/workspace/session status
/session       active Harness session
/new           select a fresh session without restarting Harness
/clear         clear local presentation only
/plugins       Capability Explorer
/capabilities  alias of /plugins
/trace         normalized observable event timeline
/agents        root/subagent topology from public events
/config        base, patch and effective requested configuration
/plugin        search/install restricted Harness plugins
/workbench     observed Cordis lifecycle timeline (dev mode only)
/history       visible past-conversation browser; `continue` uses reviewed evidence in a new session
/context       observed request usage, capacity metadata and compaction
/prompt        dshc-owned local prompt-layer projection
/permissions   fail-closed policy, capability and approval audit view
/exit          close the owned Harness runtime and exit

Use //... to send a literal model prompt beginning with /.

Doctor

dshc doctor checks the supported local path without creating a session or sending session/prompt. It reports PASS/WARN/FAIL/UNKNOWN findings for Node/workspace/config/package compatibility, provider/model selection, DeepSeek credential presence, TTY/raw-mode facts, the initialize handshake, server/protocol identity, shipped M4 sandbox/approval defaults and dshc retention policy.

pnpm dev -- doctor
pnpm dev -- doctor --workspace ./some-repo
pnpm dev -- doctor --json

The command never prints credential values, lengths, prefixes, fingerprints or environment dumps. A runtime-config override is labelled explicitly because its capability/sandbox/approval composition may differ from the shipped default. Hard configuration/compatibility failures return nonzero; missing credentials and non-TTY execution are warnings rather than invented runtime failures.

One-shot and scripted compatibility

The non-TTY/plain paths remain intentionally independent of Ink:

pnpm dev -- "inspect this repository"
pnpm dev -- run "inspect this repository"
echo "summarize the project" | pnpm dev -- --json
printf "first prompt\nsecond prompt\n/exit\n" | pnpm dev -- --interactive

Useful options:

-C, --workspace <path>
--provider <id>
--model <id>
--session <id>
--max-tokens <n>
--activity-timeout-ms <n>
--request-timeout-ms <n>
--runtime-config <path>
--dev
--interactive
--json
--debug

Taking this over

docs/HANDOVER.md is written for whoever picks this up: how to verify a change (a green suite is not enough, and the reasons are specific), the failure modes this project has actually hit, what lives where on a working machine, and the decisions that are the owner's alone.

Protocol truth

The validated baseline is DeepSeek Harness 0.1.1-rc.2, SDK server deepseek-harness-sdk-runtime, protocol 0.0.1, Node ^22.19.0 || >=24, pnpm 11.7.0.

dshc adds no private wire method. The public protocol still has no per-prompt cancel, no per-session close, no active server-to-client approval request flow, and no authoritative full runtime-plugin inventory. Therefore:

  • session/prompt remains an enqueue receipt, not an exact assistant-result RPC;
  • activity is observed from the matching durable receipt through root idle;
  • /new changes only the locally selected session;
  • active-turn Ctrl+C stops and replaces the whole owned runtime, then selects a fresh session; this is a dshc hard interrupt, not prompt cancellation or session resume;
  • doctor stops after the public initialize handshake and never uses session/prompt;
  • unavailable permission escalation fails closed rather than being fabricated by the terminal frontend;
  • /plugins labels the Harness runtime plugin inventory partial/unavailable instead of guessing it;
  • /trace never reconstructs or exposes hidden reasoning;
  • local activityId values group terminal blocks only and are not upstream message/turn/causal ids.

Developer mode does not change that wire. Lifecycle changes are official model tool calls, and /workbench is explicitly a non-authoritative retained event timeline. Dynamic code can affect the whole Harness process; the VM is not a security boundary and in-memory definitions do not survive restart.

See Protocol and upstream compatibility.

First-party terminal plugins

The terminal plane is first-party only. Built-in commands, event renderers, views and status segments register through one deterministic TerminalPluginHost.

The terminal plane is deliberately not an arbitrary-package ecosystem. /plugin install affects the child Harness composition only, accepts @deepseek-ai/ npm packages, requires an exact-version confirmation, installs with lifecycle scripts disabled, and trial-boots before replacing the live runtime. Installed plugin code still executes with the Harness child process's OS authority. See Extensions and composition.

Validation

Required CI is credential-free and blocking on:

  • Windows latest / Node 24;
  • macOS latest / Node 24;
  • Ubuntu latest / Node 24;
  • Ubuntu latest / Node 22.19.0.

Every runtime job builds the Ink/React product. The normal gate drives injected TTY product tests, fake-runtime lifecycle/security tests and bounded-retention regressions. Official published-Harness smokes cover one-shot, persistent interaction, repository read/edit/search/shell, workspace sandbox denial/escalation, built dshc doctor --json, the raw rc.2 event contract, normal/dev tool isolation and a complete host-only Cordis lifecycle. The doctor smoke deliberately removes DEEPSEEK_API_KEY and uses an unreachable model endpoint; success proves preflight does not issue a model request.

Architecture

Terminal user
    │
    ▼
 dshc
 ├─ CLI mode routing + doctor preflight
 ├─ Ink TTY product / plain fallback
 ├─ first-party terminal plugin host
 ├─ normalized transcript / trace / topology
 ├─ session selection / lifecycle
 └─ terminal security boundary
    │
    │ stdio JSON-RPC
    ▼
 Official DeepSeek Harness runtime
 ├─ models / tools / skills
 ├─ sessions / persistence
 ├─ approval / sandbox
 ├─ subagents / jobs / workflows
 └─ agent loop

All upstream/version-specific behavior stays under src/upstream/.

Next milestones

  • M7.4 — re-audited on 2026-08-26: the pinned official wire still has no versioned extension/approval capability handshake, and its closed SDK router rejects a real namespaced probe with -32603 plus an explicit unknown-runtime-method diagnostic;
  • M7.5 — remains requires-upstream; exact final-Prompt inspection and interactive Allow-once/Reject controls are not fabricated;
  • M7.6 — hardens Ask History review binding, cancellation/concurrent JSONL reads and approval-audit replay/duplicate/cross-session diagnostics;
  • #16 — retain unpromoted capability candidates behind the admission test.

License and affiliation

MIT licensed. This is an independent community project and is not affiliated with, endorsed by, or maintained by DeepSeek AI. “DeepSeek” and “DeepSeek Harness” are used only to describe interoperability with the upstream project.