Skip to main content
Glama

Codex-DSH-Orchestrator

License: MIT Node.js 22+

English | 简体中文

Codex-DSH-Orchestrator lets Codex delegate bounded work to DeepSeek Harness (DSH), follow its progress, continue the same session and review the result. Codex keeps planning and final acceptance; DSH handles implementation, code search, refactoring and tests.

Project boundary

The connect-only MCP server is registered as dsh_agentlink and connects to a user-managed DSH Host. Desktop startup, login, permissions and model credentials stay with the user; approvals require human confirmation. It is not a DSH Cordis bundle. Do not install it with dsh plugin --profile ... add ....

This is an independently maintained derivative of dsh-Agentlink. The upstream MIT license and attribution are retained in LICENSE and NOTICE. The project is independent of DeepSeek, OpenAI and the upstream maintainers.

Related MCP server: DSH Subagent MCP

Quick start

Requirements: Node.js 22+, npm, Git, Codex and the official DeepSeek Harness Desktop for your platform. Keep the checkout in a stable tools directory because setup records absolute paths.

Host path

Setup choice

Official Desktop on Windows or macOS

--gateway --desktop-auto --no-preset

Official Gateway at a known origin

--gateway --host <origin> --no-preset

Legacy rc.6 Web Host or community Windows Desktop

Use the legacy configuration

This 0.1.0-alpha.6 source snapshot includes official Desktop support on Windows and macOS. Both Windows and Apple Silicon Mac completed an inherited read-only task and same-session follow-up. Source CI covers all nine Ubuntu/Windows/macOS and Node 22/24/26 combinations; public CodeQL and the maintainer-author gate also passed. Validation records the tested builds and remaining limits. Published tags and release artifacts are listed on Releases.

Install Codex-DSH-Orchestrator from https://github.com/Fly2Kiana/Codex-DSH-Orchestrator
in a stable tools directory I approve. Check Node.js 22+, npm, Git and the selected source revision.
Run npm ci and npm run check. For official Desktop, preview:
npm run setup -- --yes --gateway --desktop-auto --no-preset --dry-run

Show the MCP and Skill targets and any conflicts. For use across projects, choose one user Skill
target; for repository-only use, retain .agents/skills/codex-dsh-orchestrator. Existing legacy
global Skill installations should be updated in place. Ask before --replace or --replace-skill.
Install only the reviewed targets, retain backups, and report any partial installation.

Leave my apps and active tasks running during preparation. Explain the application launch/restart
steps and wait for my downtime approval before authorization handoff. Keep startup authorization
in the private process pipe; do not print it or save it. Do not request provider API keys.

After I restart, verify MCP and Skill loading, then perform connection-only acceptance.
Ask separately before any model request. Report setup, connection and live-task results separately.

Manual setup and verification

Clone a fresh copy on each machine:

git clone https://github.com/Fly2Kiana/Codex-DSH-Orchestrator.git
cd Codex-DSH-Orchestrator
npm ci
npm run check

For official Desktop on Windows or macOS, preview the configuration:

npm run setup -- --yes --gateway --desktop-auto --no-preset --dry-run

The default Skill target is the checkout's .agents/skills/codex-dsh-orchestrator/. For access from any project, add --skill-path "$HOME/.agents/skills/codex-dsh-orchestrator" to both preview and installation. Existing installations under ~/.codex/skills can keep their current target; update that copy explicitly and avoid a second copy with the same skill name. These location rules follow the Codex Skill documentation.

Once the targets are reviewed, run the same setup command without --dry-run:

npm run setup -- --yes --gateway --desktop-auto --no-preset

Setup registers the bridge, keeps approval_mode = "prompt" for approvals and copies SKILL.md plus agents/openai.yaml. Conflicting MCP or Skill content requires --replace or --replace-skill, respectively. Review the conflict first. --no-skill opts out of Skill installation. Successful replacements create backups; if only one part succeeds, review the reported state before retrying.

The official Gateway uses a private in-memory authorization handoff from Desktop to a newly launched Codex process. This step starts Desktop and Codex and requires both apps to be quit first. Finish active work before following the Windows/macOS startup instructions. Keep that terminal open during use.

After the controlled launch, check /mcp or Settings for dsh_agentlink, and use /skills or $codex-dsh-orchestrator to confirm Skill discovery. A connection-only dsh_host_status then checks admission without creating a task or invoking a model. Unlike doctor, this call can exchange authorization and create a Gateway API Peer. Doctor deliberately reports Gateway admission as not_probed.

Portability and rollback

Use a fresh clone on another computer. A linked worktree's .git file refers to the original clone and cannot serve as an independent installation.

Keep DSH_BRIDGE_HOME on a reliable local filesystem. Compatible bridge processes can share it under the cooperative locking protocol; independently managed or incompatible builds need separate homes. A new home starts fresh mappings, cursors and claims while DSH retains conversation history.

Preserve the old checkout, configuration backup and installed Skill backup during an upgrade. To roll back, first review any later configuration edits, restore the intended MCP block and Skill files, then relaunch the caller at an agreed time. See Known issues for lock recovery and Windows filesystem limits.

For AI Agents

Use the focused setup/validation documents and inspect only the relevant non-sensitive configuration. Preserve unrelated MCP servers and Skills. Preparation does not authorize replacing an installation, closing an application or invoking a model.

Report the source revision, build result, installed MCP/Skill targets, caller reload status and connection result. Keep credentials, real session identifiers and personal paths out of public reports. Only the user can approve application downtime, a DSH approval request or publication.

Use it

In a project with the bridge and Skill loaded:

请委派给 DSH 完成这个有明确范围的任务,按当前项目状态交接,并由 Codex 审阅结果。

Use $codex-dsh-orchestrator for explicit invocation. The Skill also matches natural-language delegation requests. It builds a compact handoff from progress, Git state, focus files, relevant tests and constraints. DSH reads those focus files first. The bridge does not receive prior caller conversation state automatically.

Continue the same known task with dsh_followup. To resume work from a different Codex chat, metadata-only dsh_find_sessions must identify one mapped, idle root with the exact canonical workspace; dsh_attach_session checks fresh title/cwd/update preconditions before a follow-up. Titles and similar wording are insufficient for reuse. Session reuse may reduce rereads but can increase input tokens; provider cache evidence remains not_exposed without documented usage telemetry.

Model routing

Model routing is opt-in and backward-compatible for both delegation and follow-up.

Request

Behavior

Omit routing, or use inherit

Verify the session's current route; no model-selection write

flash / pro

Select an advertised official route on the current account/API-key provider

reasoningEffort

Require that exact effort in the current catalog

Visual low complexity

visualIntent="required", complexity="low": select official Flash Vision only with verified image capability

Visual high complexity

Ask the user to choose official-flash-vision or modlens-pro

Flash recognizes deepseek-flash and the legacy deepseek-v4-flash; Pro uses deepseek-v4-pro. An unavailable Pro is refused, and account/API-key providers stay separate. The bridge reads the Host catalog again after selection. Delegate and follow-up results report modelRouting.persistsAsDshDefault=true when selection saves the global default; a verification failure can leave that side effect even though no prompt was sent.

The official rc.3 session catalog omits image modalities, so a Vision display name alone cannot enable native vision. ModLens Flash is reserved for one fallback after the approved visual route exhausts bounded qualifying failures; invalid input, missing models, permissions and configuration errors do not qualify. The prompt write is never replayed. Explicit legacy modlens-flash remains accepted when visual-policy fields are omitted.

Routing policy is covered by automated tests. Current native vision, ModLens and fallback provider execution still need live qualification. Gateway capabilities describes the exact limits and the legacy Code Mode handoff.

MCP tools

Tool

Purpose

dsh_host_status

Connection state and capabilities

dsh_find_sessions

Bounded root-session metadata discovery

dsh_attach_session

Attach an exact idle root with fresh preconditions

dsh_delegate

Create a root and queue its initial prompt

dsh_followup / dsh_continue

Continue that root; queue or steer

dsh_status

Execution, pending interactions, final answer and workspace claim semantics

dsh_tail

Bounded event digests and next cursor

dsh_wait / dsh_observe

Bounded observation; one window is at most 30 seconds

dsh_cancel

Cancel the current turn or observed queue items

dsh_list

List mapped tasks

dsh_answer_question

Answer a typed pending question

dsh_resolve_approval

Human-approved allow_once or rejection

dsh_release_workspace

Release the cooperative claim; leave the DSH session open

Retain cursors/revisions before mutations. A wait window ending does not end the task; continue observation until a real terminal state or required human action. Workspace claims coordinate bridge users and do not enforce DSH filesystem permissions.

Caller support

Codex has the canonical orchestration Skill and setup above. Claude Code has a retained project installer:

npm run setup:claude -- --yes --project /absolute/path/to/project

That installer configures the legacy integration; the new official Gateway path has no fresh Claude Code live qualification. ZCode, OpenCode, Workbuddy and Claude Desktop remain deferred. See Deferred roadmap.

Project components

Project

Relationship

DeepSeek Harness / source

Official Desktop and Host runtime

DSH Desktop

Community client, retained Windows legacy discovery

ModLens

Optional vision plugin. Not maintained by or affiliated with this project

Model Context Protocol

Caller-to-bridge protocol

dsh-Agentlink

Upstream MIT code and compatibility lineage

License

MIT. Read Known issues before upgrading a shared bridge home.

Available Tools

15 tools
dsh_answer_questionA

Answer one currently pending typed DSH question request. The requestId, task lineage, question ids/order, and selections are validated locally before one non-retried /api/respond write.

Inputs: taskId (required), answers (required), requestId (required), sinceCursor, +1 more.

dsh_attach_sessionA

Attach one idle existing root DSH session to the bridge using its exact sessionId and fresh discovery preconditions. This creates or reuses bridge-local mapping/claim state and starts normal supervision reconciliation: it does not prompt DSH, create or rename a DSH session, return or persist conversation bodies, or change model routing. After success, use dsh_followup with a compact handoff when work should continue.

Inputs: sessionId (required), expectedCwd (required), expectedTitle (required), expectedUpdatedAt (required), +2 more.

dsh_cancelA
Destructive

scope=turn cancels only the active root turn and preserves queued work. scope=queue non-atomically removes each item from the latest mux queue snapshot.

Inputs: taskId (required), scope, sinceCursor, expectedRevision.

dsh_continueA

Compatibility alias for dsh_followup. Continue the same known BridgeTask and root DSH session instead of creating another delegation for the same work. Never guess an old task id; start a fresh delegation when no matching task id is known. queue targets the next turn; steer targets the active turn's next step. Optional semantic model routing is catalog-validated and re-read before the prompt; selection failure sends no prompt, but an attempted session.selectModel may already have persisted as the DSH global default. Omit routing to inherit. The write is never automatically retried.

Inputs: prompt (required), taskId (required), mode, sinceCursor, +4 more.

dsh_delegateA

Create a root session on the configured official DSH Web Host and queue the initial prompt. Before calling, put a compact handoff in prompt from known progress plus read-only Git/workspace evidence; identify focus paths and tell DSH to read those focus paths first instead of scanning the whole repository unless blocked. An explicit user choice of modelProfile or reasoningEffort always takes precedence. Otherwise the caller may choose pro for complex work and a modlens profile for visual work whose local image paths are included in the prompt; omit routing fields to inherit DSH's configured model. Explicit selection uses session.selectModel, which also persists the selection as the DSH default for later sessions. Detached by default. workspaceMode is only a bridge-local cooperative claim and does not select or verify the DSH sandbox.

Inputs: cwd (required), prompt (required), title, agentPreset, +5 more.

dsh_find_sessionsA
Read-onlyIdempotent

Read bounded metadata for existing root sessions from DSH session.list. It can filter titles exactly or by a case-sensitive substring, or narrow candidates by an exact canonical cwd, an unambiguous BridgeTask mapping, or idle state; it returns no history or raw projections. These filters narrow candidates but never authorize automatic selection, history reads, attachment, or prompting. Use the returned exact sessionId and precondition fields with dsh_attach_session; never select a session by title alone.

Inputs: cwd, title, idleOnly, mappedOnly, +3 more.

dsh_followupA

Continue the same known BridgeTask and root DSH session instead of creating another delegation for the same work. Never guess an old task id; start a fresh delegation when no matching task id is known. queue targets the next turn; steer targets the active turn's next step. Optional semantic model routing is catalog-validated and re-read before the prompt; selection failure sends no prompt, but an attempted session.selectModel may already have persisted as the DSH global default. Omit routing to inherit. The write is never automatically retried.

Inputs: prompt (required), taskId (required), mode, sinceCursor, +4 more.

dsh_host_statusA
Read-onlyIdempotent

Report the connect-only bridge state and current official DSH Web Host capabilities.

Inputs: no named parameters.

dsh_listA
Read-onlyIdempotent

List bridge task mappings enriched with current derived DSH status and bridge-local workspace claim semantics when the Host is reachable.

Inputs: no named parameters.

dsh_observeB
Read-onlyIdempotent

Compatibility observation alias. Prefer dsh_wait plus dsh_tail task cursors.

Inputs: taskId (required), afterCursor, waitSeconds.

dsh_release_workspaceA
Destructive

Explicitly release this bridge task's persistent workspace claim. This does not close the DSH session or stop other clients from editing the directory.

Inputs: taskId (required).

dsh_resolve_approvalA
Destructive

Resolve one pending DSH sandbox-escalation approval as allow_once or reject. Never auto-allows; keep this tool behind the caller's human approval prompt before permitting allow_once.

Inputs: taskId (required), outcome (required), requestId (required), sinceCursor, +1 more.

dsh_statusB
Read-onlyIdempotent

Return separate availability/execution state, root and descendant sessions, queue depths, pending interactions, final message, bridge cursor/watermarks, and bridge-local workspace claim semantics.

Inputs: taskId (required).

dsh_tailB
Read-onlyIdempotent

Read bounded event digests using bridge coordination cursors. Conversation content is fetched from DSH history when reachable and is never copied into bridge persistence.

Inputs: taskId (required), maxBytes, maxEvents, sinceCursor.

dsh_waitA
Read-onlyIdempotent

Wait at most 30 seconds for a new task cursor, status/availability change, terminal state, or pending interaction. It never waits for whole-task completion.

Inputs: taskId (required), timeoutSec, sinceCursor.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 15 tools

    Disambiguation3/5

    Most tools are distinct and the descriptions carefully narrow their responsibilities, but dsh_continue is an explicit compatibility alias for dsh_followup and dsh_observe blurs into dsh_wait/dsh_tail territory. The duplicated entry points are documented clearly enough that an agent can choose correctly, though they still reduce clarity.

    Naming Consistency4/5

    Naming is generally predictable: almost every tool uses the dsh_ prefix and snake_case, with clear action nouns like find_sessions, attach_session, resolve_approval, and release_workspace. Minor deviations such as dsh_status, dsh_list, dsh_tail, and the alias-style dsh_continue/dsh_observe keep it from being perfectly systematic.

    Tool Count4/5

    Fifteen tools is a reasonable size for a session/bridge management server, and the set stays around the core lifecycle area. The count is slightly inflated by the compatibility aliases dsh_continue and dsh_observe, which could be removed or hidden without losing functional scope.

    Completeness4/5

    The toolset covers the major workflow: find/attach sessions, delegate work, follow up, observe status, cancel work, answer questions, and handle approvals. The most obvious gap is the lack of an explicit session close/detach or full task-level teardown operation, though much of the surrounding lifecycle is present.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers