DeepSeek Harness vs Pi Agent: Plugin Runtime or Minimal Coding Harness?

Choosing a coding-agent harness increasingly means choosing an architectural philosophy, not just a model wrapper. Two projects illustrate opposite ends of that spectrum: DeepSeek Harness (DSH), a Cordis-based plugin runtime shipped in developer preview by DeepSeek AI, and Pi Agent, distributed as @earendil-works/pi-coding-agent, which describes itself plainly as a “minimal terminal coding harness.” This article compares their architecture and fit for engineering teams. It does not compare speed, intelligence, or overall safety — no controlled, same-model, same-task benchmark is available here, and none is claimed.

1. Design Philosophy and Default Complexity

DSH’s core idea is composition: model adapters, tools, sessions, approval, sandbox policy, MCP, telemetry, and both web and headless surfaces are all wired together as Cordis plugins/services, configured through profiles, bundles, and patches. This gives DSH a declarative, service-oriented shape — the harness itself is a runtime for assembling capabilities, and much of what “the agent does” is determined by which plugins and patches are active in a given profile. DSH is MIT-licensed and explicitly in developer preview, with the project itself warning about compatibility-breaking changes as the design settles.

Pi takes the opposite default stance. It ships with four model tools — read, write, edit, and bash — and nothing else turned on by default. Its own description as a “minimal terminal coding harness” is a design commitment, not a limitation to be apologized for: Pi’s authors have chosen to keep the built-in surface small and push everything else — MCP, permissions, richer tool sets — into an explicit extension layer that users opt into.

Neither posture is inherently more “capable.” DSH’s complexity buys you a structured way to compose many subsystems consistently; Pi’s minimalism buys you a small, auditable core whose behavior is easy to reason about before any extensions are added.

2. Extension/Composition Model

DSH’s extension unit is the Cordis plugin/service. Tools, approval logic, sandbox policy, telemetry, and UI surfaces are all expressed as plugins that get composed via profiles and bundles, with patches layered on top for targeted overrides. This is a genuine composition architecture: the same underlying runtime can be reconfigured into quite different agent shapes by changing which plugins are loaded and how they’re patched, without touching a separate “core.”

Pi’s extension surface is different in kind. It supports TypeScript extensions, skills, prompt templates, themes, and installable Pi packages. Pi extensions can register new tools, intercept and block tool calls, modify tool results, inject context, and customize compaction and UI. This is a meaningfully rich hook system — but it is layered onto a deliberately minimal core rather than replacing the core’s own architecture. Where DSH treats “the agent” as an assembly of plugins, Pi treats extensions as an opt-in layer around four default tools and a session model.

It’s worth being precise here: Pi’s extension capabilities (blocking calls, modifying results, injecting context) are things a user can build, not things that ship enabled. The same is true of many DSH plugin combinations — a profile that wires in strict approval and sandbox plugins is not the same as DSH having a single fixed security posture out of the box. Both systems put real configuration work on the integrator; they just distribute that work differently.

3. MCP Strategy

DSH includes a generic MCP client as a built-in component of its composed architecture — MCP servers are treated as one more thing the runtime can wire into a profile alongside adapters and tools.

Pi deliberately has no built-in MCP client. The official guidance is to use CLI tools with documentation directly, or to install or build an MCP extension when MCP connectivity is actually needed. This is a considered design choice reflecting Pi’s minimal-core philosophy: MCP is an opt-in integration rather than a default requirement for every coding session.

For teams already standardized on MCP servers, DSH’s built-in client removes an integration step. For teams that use few or no MCP servers, Pi’s opt-in approach avoids carrying that dependency by default.

4. Sandbox and Approval Model

DSH ships a fail-closed approval service and filesystem-effect sandbox modes as built-in plugins in its architecture. “Fail-closed” here means the approval layer is designed to deny by default rather than silently allow when its logic is uncertain or misconfigured — a meaningful built-in property. However, it’s important to be precise about scope: DSH’s sandbox vocabulary governs filesystem effects; it does not govern network access or process visibility. Teams relying on DSH’s sandbox modes for isolation should not assume they constrain network calls or what processes an agent-run command can see or affect.

Pi deliberately ships with no built-in permission system restricting filesystem, process, network, or credential access. Its extension hooks can block individual tool calls, but that is not a complete security boundary. The official recommendation for stronger isolation is to run Pi with Gondolin, Docker, or OpenShell, putting enforcement outside the harness at the operating-system or container layer.

Comparing these two models fairly: DSH has a named, built-in approval/sandbox subsystem with a specific and limited scope (filesystem effects, fail-closed approval). Pi has no built-in equivalent at all, and instead directs users to external containerization tools. Neither claim should be read as “DSH is safer overall” or “Pi is safer overall” — DSH’s sandbox does not cover network/process, and Pi’s recommended containers are outside the harness’s own code, so the actual security posture in both cases depends heavily on what the integrating team configures around the harness.

5. Context, Sessions, and Compaction

Pi’s session model is explicit and specific: sessions are stored as JSONL trees, supporting branching, forking, resuming, and compaction. This tree structure is a distinctive design choice — it allows a user to explore multiple conversational branches from a shared history point and resume any of them later, with compaction available to manage context size as sessions grow. Extensions can customize compaction behavior, per the extension capabilities described above.

DSH’s architecture composes “sessions” as one of the plugin/service categories wired through profiles and bundles, alongside model adapters, tools, and telemetry. The verified facts describe sessions as a first-class composed component of the runtime, but do not specify an equivalent branching/forking data structure. Teams evaluating DSH for long-running or branch-heavy workflows should check the current session plugin’s documented behavior directly rather than assuming feature parity with Pi’s JSONL tree model.

6. User Interface and Embedding/Deployment Surfaces

DSH composes Web and headless surfaces as part of its plugin architecture, meaning the same underlying runtime can be exposed through a web UI or run headlessly, with the choice of surface itself controlled through profile/bundle configuration.

Pi runs interactively in the terminal by default, and also offers print/JSON output, an RPC mode, and an SDK mode. This gives Pi multiple embedding paths without requiring a plugin-composition step: print/JSON suits scripting and CI use, RPC suits programmatic control from another process, and the SDK suits direct in-process integration.

Both approaches serve embedding use cases, but the mechanism differs: DSH exposes surfaces as composed plugins within its runtime; Pi exposes surfaces as distinct invocation modes of a single minimal binary.

7. Operational Burden and Debugging

DSH’s plugin/profile/bundle/patch architecture means operational understanding requires tracing which plugins are active in a given profile and how patches alter their behavior. This is a real burden when debugging unexpected behavior — the “effective configuration” is the composition of several layers — but it is also DSH’s main value proposition: the same primitives that make debugging require more tracing also make large-scale reconfiguration and reuse across projects more systematic. DSH’s developer-preview status and explicit compatibility-breaking-change warnings mean teams should also expect operational surfaces (plugin APIs, profile schemas) to shift between versions.

Pi’s minimal default core is easier to reason about in isolation — four tools, a defined session format, no built-in MCP or permission system to trace through. But this simplicity shifts burden elsewhere: because Pi has no built-in permission system, operational safety work (containerization, credential scoping, network isolation) has to be designed and maintained by the integrating team using external tools like Gondolin, Docker, or OpenShell. Similarly, if a team needs MCP or a richer permission model, that logic must be built or installed as an extension and then maintained as Pi’s core evolves.

Neither system removes operational work; each places it in a different location — inside the composition graph for DSH, outside the core (in extensions and external tooling) for Pi.

8. Best-Fit Teams and Workloads

DSH’s plugin-runtime architecture fits teams that expect to run multiple differently-configured agent variants from one underlying system, that want MCP connectivity built in, and that are comfortable operating a developer-preview project whose plugin APIs may change. Its fail-closed approval service and filesystem sandbox modes offer built-in scaffolding for teams that want some approval/sandbox logic without building it themselves — as long as they understand its scope stops at filesystem effects.

Pi’s minimal harness fits teams that want a small, auditable default core, that are willing to adopt external containerization for isolation, and that prefer explicit opt-in extensions (MCP, custom tools, permissions) over a built-in composed subsystem. Its multiple invocation modes (interactive, print/JSON, RPC, SDK) suit teams embedding a coding agent into varied surfaces without needing a plugin-composition step to expose each one.

Comparison Table

The table summarizes verified facts, not a verdict. A checkmark-style reading — “DSH has more built-in subsystems, so it’s more complete” or “Pi has less built-in surface, so it’s less capable” — would misstate both projects. DSH’s built-ins are scoped (its sandbox does not touch network or process visibility), and its plugin composition adds real operational tracing work. Pi’s lack of built-ins is a stated design choice with a documented mitigation path (external containers, opt-in extensions), not an oversight.

Decision Guide

Choose DSH when your team wants a single runtime that composes model adapters, tools, sessions, approval, sandboxing, MCP, telemetry, and UI surfaces through declarative profiles and bundles; you need built-in MCP connectivity without adding an extension; you want a fail-closed approval service and filesystem-effect sandboxing as a starting scaffold; and you can tolerate developer-preview instability and compatibility-breaking changes as the project matures.

Choose Pi when you want a small, auditable default core with exactly four built-in tools; you’re comfortable building or installing extensions for MCP, custom tools, or permission logic only when you actually need them; you plan to handle filesystem/process/network/credential isolation through an external container (Gondolin, Docker, or OpenShell) rather than a built-in permission system; and you value the JSONL session tree’s branching/forking/compaction model plus flexible invocation modes (interactive, print/JSON, RPC, SDK).

Evaluate both when you’re prototyping a coding-agent integration and haven’t yet decided whether you need multi-surface plugin composition (DSH) or a minimal, extensible core (Pi); when your isolation requirements are still being defined and you need to understand exactly what each system’s sandbox does and does not cover before committing; or when your MCP and permission needs are not yet fixed and you want to compare built-in composition against explicit, opt-in extension development before locking in an architecture.

References

• DeepSeek Harness official repository
• DeepSeek Harness architecture
• DeepSeek Harness MCP client
• DeepSeek Harness approval subsystem
• DeepSeek Harness filesystem-effect sandbox
• Pi Agent official repository
• Pi coding-agent guide and MCP position
• Pi containerization guide
• Pi extension API
• Pi session format