Three Paradigms of Agent Harnesses: DSH, OpenCode, and Pi

Agent harness fundamentals

An agent’s execution loop can be expressed in five steps: (1) the model decides the next action, (2) the model requests a tool call, (3) the harness executes the call in the real world (filesystem, shell, HTTP, etc.), (4) the harness returns the result as an observation , and (5) the model updates its internal state and repeats. The model only ever sees text and structured data; all side‑effects are performed by the harness, which therefore defines the model’s perception boundary.

dsh – “everything is a plugin”

dsh’s core claim is that no component is irreplaceable. Built on the Cordis kernel (a plugin runtime derived from the Koishi chatbot framework, which has run in production for four years and accumulated >4,000 community plugins), dsh treats the model adapter, tool registry, session store, sandbox, scheduler, UI, and even the main agent loop as interchangeable plugins.

The Cordis paper describes this as a “spatiotemporal composable programming paradigm” where any service can be swapped at runtime with safe dependency decoupling.

dsh ships four built‑in profiles :

standard – full coding agent with sub‑agents, workflow, and planning.

minimal – only file operations and text editing, useful for model testing.

PTC (programmatic tool calling) – compiles a multi‑step tool workflow into a single TypeScript program, reducing round‑trip latency.

create – lets users define new profiles and validates them at runtime.

Because dsh is in developer preview, its plugin API changes frequently; it is positioned as an experimental platform for deep customization rather than a stable production dependency.

OpenCode – production‑grade, opinionated harness

OpenCode packages the harness as a mature product. It provides two built‑in agents, Plan and Build , LSP‑based code intelligence, and support for >75 model providers.

The /init command scans a repository, infers project structure, and generates an AGENTS.md file. This file travels with the codebase and serves as a long‑term instruction set for agents.

OpenCode hard‑codes several best‑practice defaults:

Plan mode restricts file modifications.

Build mode opens all permissions.

LSP compilation errors are injected directly into the model’s context.

An MCP server can be plugged in.

A peripheral plugin system exists for edge extensions (adding a tool, a command, or an MCP server), but the core agent loop is fixed and not intended to be replaced. A built‑in permission system makes the harness suitable for production use without exposing the internal loop.

Pi – minimal kernel with runtime hooks

Pi reduces the harness to four primitive tools:

read

write

edit

bash

The system prompt is limited to 1,000 tokens. Pi deliberately omits MCP, sub‑agents, planning mode, and permission dialogs. Its creator, Mario Zechner (badlogic), argues that modern models have already been trained on massive codebases and tool‑calling patterns, so the harness only needs to provide minimal infrastructure.

Pi exposes >25 TypeScript hook points covering the full agent lifecycle, e.g.: input – intercepts and rewrites user input. before_agent_start – injects custom system prompts. tool_call – can abort, modify, or fine‑tune tool execution. agent_start / agent_end, turn_start / turn_end – lifecycle events for deeper instrumentation.

Session state is stored as a tree, enabling branching and parallel experimentation without duplicating the entire context.

The trade‑off is that Pi does not provide a built‑in permission layer; it inherits the host process’s privileges. Users must add containers or sandboxes themselves if isolation is required.

Comparative dimensions

Core architecture – dsh: all components are plugins; OpenCode: fixed loop with peripheral extensibility; Pi: minimal kernel with runtime hooks.

Customization entry point – dsh: replace plugins or combine profiles; OpenCode: edit AGENTS.md, run commands, or install plugins; Pi: write or import TypeScript extensions.

Built‑in workflow – dsh: four preset profiles; OpenCode: Plan & Build modes; Pi: none (provided by extensions).

Security boundary – dsh: permission‑check plugins; OpenCode: built‑in permission system; Pi: none by default, user‑added.

Maturity – dsh: developer preview; OpenCode: production‑grade; Pi: production‑grade core but minimal.

Interoperability and independent evaluation

dsh includes a dsh-import-agents plugin that can import historical sessions and configurations from Pi, OpenCode, Codex, and Claude Code. Conversely, the opencode-pi extension lets Pi use OpenCode’s model channel.

Independent benchmarks reported mixed outcomes: in one test Pi and OpenCode achieved identical task‑success rates; in another test Pi scored 21/30 versus OpenCode’s 19/30. The differences stem from divergent task sets and cost metrics, so the results do not prescribe a definitive winner.

References

GitHub – earendil-works/pi: AI agent toolkit

Pi Coding Agent

OpenCode Harness

What is DeepSeek Harness (dsh)? The Open‑Source …

DeepSeek Harness vs OpenCode: The Token Usage Gap …

Pi: A Coding Agent Harness You Can Reshape Around Your …

opencode Harness — Run the Open‑Source Agent Server‑ …

0xsline/awesome-deepseek-harness – GitHub