Preface¶

In agent environments like DSH, where “everything is a plugin,” the Agent loop needs a swappable primary model Provider. If developers already maintain a local Codex CLI login state and want to directly select the local Codex App Server as the primary model within the Harness Agent loop, dsh-llm-codex-app-server provides this integration.

It is an out-of-tree Harness bundle that does not modify the deepseek-harness repository after installation. Below, we introduce its capability boundaries, installation methods, and important considerations.

Plugin Positioning¶

dsh-llm-codex-app-server is a DeepSeek Harness LLM provider that uses a locally authenticated Codex App Server under the hood.

Its core action is to register a primary model Provider named codex-local with DSH, allowing the Harness Agent loop to use it directly during model selection.

The repository URL is:

https://github.com/wss534857356/dsh-plugin-codex

This plugin targets the following DSH version range:

>=0.1.2-alpha.1 <0.2.0

Core Capabilities¶

Registering as a Harness Primary Model Provider¶

This plugin wraps the local Codex App Server into a primary model Provider that Harness can invoke.

After installation, codex-local will appear as a selectable Provider in the Harness Agent loop. In other words, it doesn’t simply expose an external command; it integrates the Codex App Server into DSH’s model invocation path.

Reusing Local Codex Login State¶

The plugin uses the native Codex account state under CODEX_HOME.

It does not read, copy, log, or store OAuth tokens or API keys. For users, this means authentication remains handled by the local Codex CLI system, and the plugin itself does not take on the responsibility of key storage.

Session Reuse and Cold Start¶

In regular Harness sessions, the plugin reuses a fixed version of the Codex App Server:

@openai/codex@0.147.0

The reuse condition is that this App Server runs in a private empty directory, and a temporary thread remains available while a bounded cache lease is still valid.

When a cold thread needs to be rebuilt, the plugin injects recorded Harness messages before an empty turn to restore context. Subsequent normal user messages are sent via native turn input.

The Harness system text is provided as the App Server’s base instructions.

Tool Invocation and harness_skill¶

The plugin declares Harness tools under the deepseek_harness App Server namespace.

It also exposes the outer Harness skill tool as:

harness_skill

The parameter schema for this tool only accepts names that exist in the current Harness session catalog. This ensures that skill names callable from the Codex side remain constrained by the current Harness session catalog.

When the App Server requests a declared tool in the deepseek_harness namespace, the plugin issues a real Harness tool-call, ending the current model step while keeping the App Server callback pending.

Note: a failed or rejected Codex-native action still counts as an action outcome; unless the App Server reports that the turn itself failed, it does not directly cause the Harness model request to fail.

Stream Events, Statistics, and Image Attachments¶

The plugin converts the following information into Harness stream events:

• reasoning
• assistant text
• usage
• Codex-owned context
• diagnostics
• action lifecycles

Codex cached input is reported via Harness’s cacheReadTokens. This allows standard token meters and conversation statistics to display cache hit ratios without requiring Provider-specific UI.

For images and tool results containing images, the plugin preserves them as durable ImageAttachmentRef values. Near the App Server boundary, they are temporarily converted only as required by the protocol.

If the projected base64 payload exceeds:

maxRequestImageBytes

the plugin deterministically replaces the oldest model-visible images. The documentation states that preserved images do not persist data URLs.

Browser Rendering and Settings Card¶

The plugin includes a browser extension.

It shadows the standard Assistant cell and renders codex-action blocks. The rendering includes Harness’s compact disclosure row and state dot.

It also provides a Codex App Server settings card through DSH’s:

settings.plugin.item

extension point.

Auxiliary Capabilities¶

The plugin supports compaction-basic. This auxiliary request uses a one-shot Codex model process.

It also conditionally intercepts web_search calls from Codex Agents. Non-Codex Agent calls continue to use the original provider chain.

Installation and Enablement¶

Prerequisites¶

First, confirm that the local Codex CLI is logged in:

codex login

Then install the plugin. After installation, dump the configuration to verify registration before starting the DSH Web profile.

Installing the Release Version¶

dsh plugin --profile web add dsh-llm-codex-app-server@latest
dsh --profile web --dump-config
dsh --profile web

The first step installs the plugin, the second checks the current profile’s dump configuration, and the third starts the Web profile.

Building from Source¶

To use artifacts built from a local checkout, install dependencies and run checks first:

pnpm install --frozen-lockfile
pnpm run check

pnpm run check executes the repository-defined checks and packaging process, producing a tarball that can be installed.

Then install the generated tarball into the Harness profile:

dsh plugin --profile web add ./dist/dsh-llm-codex-app-server-<version>.tgz
dsh --profile web --dump-config
dsh --profile web

Use the actual tarball name generated by the repository rather than manually constructing an installation source.

Typical Usage¶

A basic enablement flow is as follows:

1. Complete Codex CLI authentication:

codex login

2. Install the release version:

dsh plugin --profile web add dsh-llm-codex-app-server@latest

3. Check whether the plugin has entered the current profile configuration:

dsh --profile web --dump-config

4. Start the DSH Web profile:

dsh --profile web

After startup, codex-local will exist as a selectable primary model Provider in the Harness Agent loop. Developers can use it for Harness sessions that require a local Codex App Server.

Suitable Scenarios and Considerations¶

Users suited for this plugin typically:

• Already use Codex CLI locally with a valid login state;
• Want the Harness Agent loop in the DSH Web profile to select the local Codex App Server;
• Need to map Codex’s reasoning, assistant text, usage, diagnostics, and action lifecycles back to Harness stream events;
• Need the Codex App Server settings card and browser rendering of codex-action blocks.

Before use, note the following:

• This plugin is an out-of-tree Harness bundle; installation itself does not modify the deepseek-harness repository.
• The plugin declares that it does not read, copy, log, or store OAuth tokens or API keys, but authentication state still originates from local CODEX_HOME.
• Image attachments are preserved as durable ImageAttachmentRef values; the documentation states that preserved images do not persist data URLs.
• To generate project files such as public/example.png, Codex still needs to request a declared Harness mutation tool with an explicit destination. Chat attachments themselves do not implicitly become workspace mutations.
• thread/start is a provider lifecycle disclosure and should not be interpreted as evidence that the model executed a native action.
• The plugin runs within the permission context of the current dsh process. Before installation, inspect the source code, dependencies, and license files in the repository. The documentation does not explicitly state the license type; a LICENSE file is visible in the repository file listing, and the specific terms should be determined by the repository content.

Conclusion¶

The value of dsh-llm-codex-app-server lies in connecting the locally authenticated Codex App Server to DSH’s primary model Provider layer while preserving Harness’s tool invocation, stream events, image attachments, and web rendering conventions.

Repository:

https://github.com/wss534857356/dsh-plugin-codex

If browsing plugins in the DSH community directory, you can also search for dsh-llm-codex-app-server. This article does not include unverified directory page URLs.