Why Is Everything a Plugin in DeepSeek Harness? An Architecture Walkthrough in 11 Diagrams

A visual walkthrough of plugin lifecycles, the agent loop, session logs and layered configuration—and what they mean for real-world delivery.

DeepSeek Harness (DSH) is DeepSeek’s open-source AI agent framework. The developer-preview version discussed here is released under the MIT licence, with source code available in the deepseek-ai/deepseek-harness GitHub repository.

First, what is a harness? DeepSeek puts it this way: Agent = Model + Harness. The model supplies the intelligence; the harness enables it to understand its environment, use tools and keep working in real systems. Think of a car’s chassis, steering wheel and dashboard: they do not produce power, but they determine how that power reaches the road.

DSH’s defining choice is to avoid a fixed core of agent capabilities. The loop, logging, retries, approval, context compaction, model access and interface are replaceable building blocks. Its guiding phrase is “Everything is a plugin”. Here, “no fixed core” does not mean there is no kernel: the Cordis kernel manages loading, unloading and dependencies, while plugins supply the agent’s capabilities.

This article uses 11 diagrams to explain how those blocks fit together, how they cooperate and why the architecture is built this way. No technical background is required. It is written for people evaluating agent frameworks for their teams.

01 / What it is: a framework without a fixed agent core

Start with the whole map. Capabilities commonly described as framework features—approval, retries, context compaction, session logs, sandboxing, model access and the web interface—are plugins in DSH, using the same mechanism as your own extensions. The foundation handles their lifecycle: loading, unloading and dependencies.

Compare that with a familiar design: a fixed core with a few extension points. The core owns the loop, memory and retries, while the framework author decides which hooks to expose and where to put them.

DSH reverses that arrangement:

For example, compatibility with Claude Code hooks is itself an ordinary plugin. It follows the same loading and unloading path as an extension obtained from the community or written by you, rather than relying on a privileged route.

There is a cost. Many blocks jointly determine behaviour, which makes failures harder to trace. In a conventional framework, you might start with the core’s source code. In DSH, you first need to identify which plugins interacted at which stage. Greater freedom brings additional debugging work.

The foundation is built on Cordis, an existing open-source plugin system. Choosing a mature plugin substrate rather than inventing a new one is an engineering decision worth noticing.

02 / How the blocks fit: registration, lifecycle and the loop

A plugin is a new colleague, not a patch

Some plugin systems feel like patches inserted into an existing application. DSH’s model is registration: a plugin declares the capabilities it provides through the host’s interfaces. Think of a colleague registering their responsibilities on their first day, rather than rearranging everyone else’s desk. This describes the intended extension model, not a security guarantee that plugin code cannot alter shared state.

Five common registrations correspond to five kinds of capability:

The key rule is that registration comes with automatic disposal. Unloading a plugin removes the tools, prompts, event subscriptions, services and interface elements registered through the managed lifecycle. The purpose is to keep the foundation clean as the number of plugins grows. It does not automatically undo external side effects or unmanaged resources created by plugin code.

Three lifecycle states: wait, work, leave

Each plugin declares the services it depends on. The foundation uses those dependencies to decide when the plugin can start and when it must stop:

This supports replacing plugins without restarting, giving different conversations different capabilities, and allowing an agent to add capabilities at runtime. Runtime extension is an important architectural possibility, although it still depends on the permissions and plugins available in a particular deployment.

The agent loop: six stages around the dial

The loop itself is deliberately straightforward. The diagram shows six stages:

Retry, compaction and approval are supplied by other plugins at the intervention points marked in red. A compliance check before tool execution can attach at stage ⑤ rather than requiring a rewrite of the loop.

In the loop described by the supplied diagrams, there is no fixed maximum step count. A step limit is another policy to add. When evaluating a deployed configuration, check its actual stop conditions and budget controls rather than assuming the default is suitable for your workload.

03 / One ledger: the underestimated session log

If we had to pick one design to remember, it would be the session log. The rule is simple: append records instead of rewriting past entries. The system prompt belongs in that record alongside user messages and model responses.

That shared record provides the basis for six useful capabilities:

Our view is that append-only logs are among the most underestimated design choices in agent systems. They attract little attention in a demo, yet become crucial when a team needs to reconstruct what happened. DSH gives traceability a structural foundation. A production audit system still needs appropriate retention, access control, integrity protection and coverage of external systems.

The diagram expresses the central idea as:

Read this as a practical test: to understand a plugin’s effect, inspect the entries it adds and how context is assembled from them. Documentation describes intent; the recorded trajectory shows what happened in a particular run.

Plugins cooperate through broadcasts and gates

Plugins do not need to know each other directly. The event system offers two broad patterns:

Interception is a powerful extension point. Retry, compaction, approval, sandbox and planning behaviour can be supplied through these events, using the same mechanism available to application-specific plugins.

One warning deserves particular attention: when several plugins intercept the same event, order can affect the result. If both plugin A and plugin B modify a request, reversing them may change the outcome. Test the composition of handlers, not just whether each plugin works on its own.

04 / Assembly: lists layered on lists

The installed plugins are described by a list. The diagrams describe three kinds of edit: insert, replace and disable. Lists are then combined in layers, with later layers overriding earlier ones:

This addresses a familiar software problem: how vendor upgrades coexist with local customisation. The vendor updates the base layer while client and personal changes remain in their own layers. Preserving those files does not guarantee compatibility with every new plugin version; upgrades still need validation.

The separation comes from the assembly model itself. Each party’s changes have a defined place, rather than being mixed into the same vendor-owned configuration.

Plugin, bundle, patch, profile, preset: five positions on one assembly line

Only plugins actually run. The other four terms answer a shared question: which plugins, with what configuration, for whom?

The process has two scopes. The host scope is shared across the process and configured by the profile: model services, logging, tool registries and the web interface. The agent scope belongs to each conversation and is configured by its preset. Presets use the same plugin-list syntax; removing the bash entry removes that capability from the role’s configuration.

One process can therefore host a research conversation, a compliance conversation and a macro-analysis conversation with different configurations. The result is a shared runtime with individually assembled agent roles.

05 / Context: MCP, Skills, Hooks and delivery

If MCP and Skills already exist, why have a plugin system as well? The diagram compares their typical responsibilities:

A useful analogy is a browser extension: it lives inside the host and can change aspects of the host’s behaviour. The comparison is about architectural roles, not a strict equivalence between technologies.

MCP integrations and Skills can be more portable across platforms that support them, although compatibility must still be checked. A useful division is to put reusable data access and methods in portable integrations, and use DSH plugins for behaviour tied to this runtime—interception, context injection or UI extensions.

What this means for forward-deployed engineering

The challenge in forward-deployed engineering (FDE) is not simply building the first agent for the first client. It is whether work from the first nine clients remains reusable for the tenth. Viewed that way, the architecture responds to seven practical delivery needs:

The supplied diagram reports a cache-hit rate above 95%. We have not reproduced that result in our own environment, so treat it as an unverified reference rather than a performance promise. Cache effectiveness depends on conversation structure and usage; someone else’s measurement cannot replace your own cost model.

The supplied materials also identify three limitations to check against the version you intend to deploy:

These limitations also suggest useful areas to build: isolation within the runtime, the relationship between team memory and the session log, and a multi-user permission model. Delivery teams can turn those gaps into reusable product capabilities.

A practical first step

Run DSH, export the log from one complete task and read it from beginning to end. With Node.js installed, the official quick-start command is:

npx @deepseek-ai/dsh web

Check whether the system prompt and every item of context supplied to the model are represented in the record. Then try reconstructing the task from it. A log that supports that investigation gives you a concrete basis for assessing recovery, forking and traceability.

DSH remains a developer preview, and its core plugins and APIs are expected to evolve. At this stage, understanding the architecture is the useful investment: it gives you a basis for judging future changes, rather than merely keeping up with individual API revisions.