Zum Hauptinhalt springen
A

dsh-local-codex

anzerwhite/dsh-local-codex

Per-session Codex mode: send a trigger word or /codex, and that one DSH session is handled by your local Codex CLI, with streamed replies plus command and file-change tool cards inline.

Installation

dsh plugin --profile web add github:anzerwhite/dsh-local-codex

README

Local Codex Mode icon

Local Codex Mode

Give one DeepSeek Harness session to your local Codex CLI — and watch it work inline.

release license DSH Codex Host only stars

中文 · Install · Quick start · Configuration · Design · Changelog

dsh-local-codex is a Host plugin for DeepSeek Harness (DSH) that hands one session to your local Codex CLI. Say “使用codex模式” (or run /codex on) and that conversation switches to Codex: replies stream into the existing chat, and every command or file change Codex performs shows up as a native, collapsible tool card in the same conversation.

The mode is per session. New sessions and forks start with it off, DSH restarts resume the same Codex thread, and one session switching to Codex never changes how the rest of your DSH workspace behaves.

You:   使用codex模式:跑一下单元测试,失败的话修掉
DSH:   ✓ Codex Mode enabled for this session → codex/<your Codex model>
Codex: I'll run the test suite first.
       ▸ codex_activity   (pnpm test — exit code 1)
       …
       Fixed the failing assertion and re-ran the suite.

Table of Contents

Why Local Codex Mode

  • Use the Codex you already configured. Same ~/.codex/config.toml, same provider, same model, same hooks, skills and plugins — no second account and no re-login.
  • No context copying. The DSH session is the Codex conversation. You keep one timeline instead of pasting prompts between a chat window and a terminal.
  • Native DSH experience. Streaming replies, tool cards, approval cards, Stop, session history, persistence and new-session behavior all come from DSH itself.
  • Scoped by design. Only the session you enabled is affected; new sessions, forks and every other DSH session keep their normal model and tools.
  • Nothing leaks behind. /codex off restores the previous DSH model route and releases the Codex thread so native Codex can reopen it.

Features

FeatureDetail
Per-session takeoverA trigger word or /codex on|off|status controls one session; DSH's model and tools step aside only there.
Inline streamingCodex text streams through DSH's standard assistant stream.
Native tool cardsCommand executions, file changes, MCP calls and web searches become real tool/call + tool/result events rendered by DSH's collapsible tool cards.
Local Codex runtimeDrives codex app-server with your Codex config; one Codex thread per DSH session.
Thinking effortminimal / low / medium / high / xhigh exposed to DSH and forwarded per turn (max → xhigh).
Session persistenceMode + Codex thread id are stored per session; DSH restarts resume the same thread.
DSH-authoritative permissionsSession sandbox/approval presets are mapped onto Codex's per-turn sandboxPolicy / approvalPolicy; Codex approvals appear as DSH approval cards.
Clean stop & recoveryStop interrupts the active Codex turn and keeps partial output; failures surface an error and rebuild the app-server.
Thread lease release/codex off unsubscribes the Codex thread, and the app-server unloads it immediately so native Codex can reopen the session.
AttachmentsComposer images become localImage inputs; files are materialized on disk and their path is passed to Codex.
Zero client codeEverything renders through standard DSH session events and the existing Web UI.

Requirements & compatibility

ComponentVersion / requirement
DeepSeek Harness0.2.1-rc.x, Web profile (Host-only plugin; no client bundle)
Codex CLI0.170.x — default path /root/.npm-global/bin/codex, override with codexBin
Codex configuration~/.codex/config.toml (custom providers supported; codex login only if your provider needs it)
Package managerpnpm available to the profile (used by DSH Plugin Manager to install zod)
Model accessA provider reachable by your Codex installation; the plugin does not manage Codex credentials
PlatformWherever DSH and Codex CLI run; the default codexBin is a Linux path, so set codexBin explicitly on other platforms

codex app-server is an experimental Codex surface. This release pins the Codex CLI 0.170.x protocol baseline and tolerates unknown notifications; upgrading Codex may require a compatibility pass.

Install

From the plugin market / prebuilt release tarball

dsh plugin --profile web add https://github.com/Anzerwhite/dsh-local-codex/releases/download/v0.1.0/dsh-local-codex-0.1.0.tgz

This is the same prebuilt tarball the DSH plugin market serves. The plugin is listed in the community catalog: https://awesome-dsh-plugin.com/p/Anzerwhite/dsh-local-codex/ — reload the DSH page and search dsh-local-codex in Plugins → Discover. The release tarball installs the same artifact immediately.

From npm (after the npm release)

dsh plugin --profile web add dsh-local-codex

From source (development)

git clone https://github.com/Anzerwhite/dsh-local-codex.git
cd dsh-local-codex
dsh plugin --profile web add -w "$PWD"

After changing source files, toggle the bundle off/on in Plugins (or restart dsh web) to load the new module generation.

Uninstall

dsh plugin --profile web remove dsh-local-codex

Removing the plugin keeps each session's saved mode record (harmless) and releases Codex threads it held.

Quick start

  1. Install the plugin and restart or reload the DSH profile.
  2. Open a session — the model picker still shows your usual DSH model.
  3. Send 使用codex模式 (or /codex on), then talk to Codex as usual.

Trigger phrases & commands

Sentence-initial, case-insensitive. The trigger itself never enters the model transcript.

ActionWhat to send
Enable (no content)使用codex模式 / 开启codex模式 / 进入codex模式 / 切换到codex模式 / use codex mode / enable codex mode / enter codex mode / codex mode on
Enable and run content使用codex模式:帮我修复这个测试 — enables mode and sends “帮我修复这个测试” as the first Codex turn
Disable退出codex模式 / 关闭codex模式 / 结束codex模式 / exit codex mode / disable codex mode / codex mode off
Explicit control/codex on · /codex off · /codex status

While mode is on, the session's model shows as codex/<your Codex model>; /codex status reports the model, thinking effort and Codex thread id.

Configuration

Configuration is optional; defaults target a standard local Codex install. Add a config block to the plugin row in your profile patch (cordis.patch.yml) to override them:

- id: codex-mode
  config:
    codexBin: /root/.npm-global/bin/codex
    reasoningEffort: xhigh
KeyDefaultMeaning
codexBin/root/.npm-global/bin/codexCodex CLI executable.
providerNamecodexLLM provider route registered with DSH.
modelmodel in ~/.codex/config.tomlModel id exposed to the DSH picker.
cwdsession working directoryOverride the Codex thread working directory.
requestTimeoutMs60000app-server request timeout.
bootstrapLimitChars24000Character budget of the history digest injected once when the Codex thread is created.
reasoningEffortCodex config model_reasoning_effortDefault thinking effort.
reasoningSummaryCodex configPer-turn summary override (auto / concise / detailed / none).
codexEffortsfive built-in tiersThinking tiers exposed to DSH.
maxBridgeCallsPerTurn200Safety budget for bridged Codex actions in one user turn.
defaultSandbox / defaultApprovaldanger-full-access / neverFallback when the DSH permission preset cannot be read.
attachmentsDirsystem temp dirWhere image/file attachments are materialized.

How it works

flowchart LR
  UI[DSH Web UI] --> LOOP[DSH agent loop]
  LOOP -->|agent/pre-step, agent/request| MODE[Mode controller]
  LOOP -->|llm.stream| ADAPTER[Codex adapter]
  ADAPTER -->|stdio JSON-RPC| SERVER[codex app-server]
  SERVER --> THREAD[Local Codex thread]
  ADAPTER -.->|synthetic tool-call| BRIDGE[codex_activity bridge tool]
  BRIDGE -.->|tool/call + tool/result| LOOP

The plugin registers an LLM provider adapter that drives codex app-server — one Codex thread per DSH session. Assistant text and reasoning travel through standard stream chunks; tool activity is bridged into real session events so the existing chat UI renders it natively. A mode controller owns session state, model routing and permission mapping. No DSH core changes, no custom client bundle.

FactValue
npm packagedsh-local-codex
Bundle row idcodex-mode
LLM provider routecodex
Display-only toolcodex_activity
Client bundlenone (Host-only)

Further reading: design · architecture decisions · implementation contract · verification log.

Permissions & security

  • DSH preset is authoritative. Each Codex turn receives sandbox/approval mapped from the DSH session's permission preset (read-only / workspace-write / danger-full-access). With the danger-full-access preset, Codex commands run with full local access — choose a stricter preset first if that is not what you want.
  • Approvals raised by Codex become DSH approval cards; declining or cancelling ends that Codex action.
  • Thread lease. While mode is on, DSH holds the Codex thread and native Codex reports the session as busy. /codex off, agent disposal or plugin unload release it.
  • Privacy. Conversation content is sent to the model provider named in your Codex configuration — the same trust boundary as running Codex directly.
  • Minimal surface. The plugin registers exactly one display-only tool (codex_activity), never re-runs Codex commands, and adds no network endpoints.
  • Secrets. DSH approval and permission settings are respected; the plugin never reads your Codex auth files.

Limitations

  • The first turn of a resumed Codex thread can take 5–30 s (Codex hooks/skills load); there is no progress indicator yet.
  • Reasoning text is provider-dependent: some providers return only reasoning token counts. The thinking tier is still visible and selectable.
  • Attachments are implemented but not yet heavily battle-tested; very large tool output is capped by DSH's spill policy.
  • If another plugin also spawns codex app-server (for example a remote-workspace plugin), prefer running one at a time to avoid thread-writer contention.
  • Generic DSH tool cards are used for Codex actions; native terminal/diff cards are on the roadmap.

Troubleshooting

SymptomFix
/codex status shows thread “(not created yet)” right after enablingNormal — the thread is created on the next message.
Native Codex says the session is lockedCodex mode still holds the thread; run /codex off first.
First reply after enabling is slowThread creation/resume plus Codex hooks can take seconds; later turns are fast.
Model picker does not show the codex modelConfirm the plugin is active under Plugins → Installed and that codexBin points to a working Codex CLI.
A trigger phrase does nothingIt must start the message; use /codex on as a fallback.
Plugin fails to activateThe profile needs pnpm for dependency installation; check DSH logs for the failing row.

Roadmap

  • npm publication (the community-catalog listing is already merged).
  • Optional native terminal / diff card rendering for Codex actions.
  • End-to-end coverage for attachments and Codex approval round-trips.
  • Progress indicator while a Codex thread is resumed.

Development

node test/scenarios.mjs            # headless end-to-end scenarios (S1–S3)
node test/run-headless.mjs --help  # one-shot headless runner with assertions

Read docs/impl-contract.md before changing module boundaries. src/ is plain ESM JavaScript with no build step.

License

MIT


Not affiliated with OpenAI or DeepSeek. Codex is a CLI from OpenAI; DeepSeek Harness is a separate project. This plugin only connects the two locally.

Ähnliche Plugins