Preface¶

DSH’s philosophy is “everything is a plugin.” The main agent can delegate tasks to subagents via the subagent mechanism. However, ordinary subagents run inside DSH using the same environment as the main conversation. If you want a specific task to be handled by OpenAI Codex—using Codex’s own model and toolchain, running in a process isolated from the main conversation—manually switching terminals, executing, and pasting the results back into the session is a very fragmented process.

dsh-subagent-codex fills this gap. Below is an introduction to its positioning, implementation method, and usage.

What is this¶

dsh-subagent-codex (current version 0.1.1) is maintained by mjylfz and is licensed under the MIT License. Upon installation, a subagent_codex tool is registered in the DSH session: you or the main agent pass the task description to it, the plugin spawns an independent Codex CLI task locally to execute it, and brings the final output back to the main conversation after completion. The task is completed within Codex’s environment, completely isolated from the DSH main conversation—briefly, DSH handles the orchestration, and Codex handles the execution.

In terms of implementation, the plugin follows DSH’s SubagentProvider interface (the out-of-process contract of @deepseek-ai/dsh-subagent) and registers a provider named codex.

Mechanism of Operation¶

One call corresponds to one independent task¶

subagent_codex is a one-shot tool, spawning once for every call:

codex exec -- --skip-git-repo-check <prompt>

The plugin parses the JSONL event stream output by Codex, takes the text of the last agent_message as the final output, and returns it to the delegator.

Results are always returned as terminal state¶

The plugin supports cancellation (sending SIGKILL to the process when triggered by AbortSignal), timeouts, and output truncation. Regardless of whether it ends normally, is aborted, or fails, the result is parsed as a terminal state and returned without throwing an exception into the main conversation. The main agent receives a processable return value, not an interruption.

Every run has complete records¶

The plugin starts Codex without the --ephemeral flag, writing the complete session to disk for every call:

~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-<timestamp>-<session-id>.jsonl

The file contains the complete conversation for this task: the input, Codex’s intermediate processes, and the final output. Afterwards, you can use codex resume to resume that session, or use codex archive to archive it.

Configuration¶

Supported configuration items for the provider line are as follows:

- id: subagent-codex
  name: 'dsh-subagent-codex'
  config:
    command: codex            # codex CLI executable file (PATH name or absolute path)
    cwd: /path/to/workdir     # optional, working directory for the subtask (defaults to inheriting the parent session workspace)
    model: o3                 # optional, specify model (codex exec -m)
    sandbox: workspace-write  # optional: read-only | workspace-write | danger-full-access
    timeoutMs: 600000         # timeout for a single task (milliseconds), default 600000
    maxOutputChars: 40000     # upper limit of output returned to the delegator, default 40000

Pay special attention to the values of command and sandbox: command determines where the plugin finds the codex executable file; sandbox controls the file system permission level when Codex executes the task.

Installation and Activation¶

First, confirm three prerequisites:

Node >= 20;
DeepSeek Harness is installed;
Codex CLI is installed and logged in (i.e., ~/.codex/auth.json exists). No need to install the Codex desktop app; the plugin calls the codex CLI directly.

Then, execute the installation command:

dsh plugin --profile web add dsh-subagent-codex

You can also install using a local tgz:

dsh plugin --profile web add file:/path/to/dsh-subagent-codex-0.1.1.tgz

The plugin automatically adds itself to the bundle stack via the dsh.bundle declaration (cordis.patch.yml). After installation, restart DSH and open a new session to use it; the tool name is subagent_codex.

Typical Usage¶

Just say it directly in the session, for example:

让 codex 调研一下大语言模型推理加速的最新论文进展，整理成一篇带对比的综述

Or “Let the codex subagent do XX.” Several typical scenarios:

Competitor research: Ask codex to compare pricing, features, pros and cons of 3 mainstream note-taking apps, and provide selection suggestions and reporting materials;
Learning: Ask codex to break down “What is blockchain” into 5 progressive sub-questions, cross-verify from multiple sources, and output a learning document with FAQs;
Content planning: Ask codex to plan a viral post for Xiaohongshu, providing 3 topic directions, titles, opening hooks, body outlines, and 5 supporting materials;
Development overhaul: Ask codex to migrate user authentication from JWT to OAuth2, modify the auth middleware, add migration scripts, write unit and integration tests, and organize commit messages.

The common point of these tasks is that they are delivered in chunks and you get the finished product back in a single call, making them suitable for being delegated to Codex to complete independently.

Applicable Scenarios and Precautions¶

Suitable for: One-time, independently completed tasks (research, literature reviews, proposals, complete overhauls), provided you want to leverage Codex’s model and toolchain.

Not suitable for: Tasks that need to be completed inside DSH—such as calling DSH’s memory, conversation history, or other DSH tools. These tasks should be delegated to a normal subagent.

Note a few points before use:

Boundary of external process capabilities. The provider does not declare any start capabilities (NO_START_CAPABILITIES), so the external CLI cannot forcibly enforce outputSchema / maxDepth / toolFilter / persona.
No runtime records in the DSH sidebar. External process providers do not create DSH sessions, so you won’t see the codex subagent’s runtime records in the DSH sidebar. To view the process, check the ~/.codex/sessions/ directory.
Token consumption. Every call uses the account logged into ~/.codex to run Codex, consuming the corresponding OpenAI/Codex token quota.
Cannot find codex command (spawn ENOENT). First execute codex --version to confirm installation; if installed in a non-default location, point the command in the configuration to an absolute path, e.g., command: /path/to/codex.

Finally, like all DSH plugins, the plugin runs with the permissions of the current dsh process. Before installation, it is recommended to read the source code and license (this project is MIT) to ensure it meets your security requirements.

Summary¶

dsh-subagent-codex does a single thing well: delegates tasks from the DSH session to the local Codex CLI and reliably brings the results back. The one-shot semantics, terminal state returns, and complete session records on disk allow the main agent to confidently outsource chunked work.

GitHub: https://github.com/mjylfz/dsh-subagent-codex
Community Plugin Directory: https://www.skillhub.cn/plugins/mjylfz/dsh-subagent-codex

dsh-subagent-codex: Delegating tasks to local Codex CLI in DeepSeek Harness