DSH × Codex Bridge

Connect Codex's decision-making with DSH's execution.

English · Installation · Usage · Architecture

dsh-codex-bridge is an open-source Agent infrastructure for developers: Codex handles goal decomposition, delegation strategy selection, and acceptance evidence; DeepSeek Harness (DSH) executes code, tests, and internal Sub-Agent work within a specified Profile; the Bridge handles protocol, isolated workspaces, task lifecycle, and auditable artifacts.

Project Status

Source available | 0.1.0-alpha.1 | DSH 0.1.0-rc.8 closed loop verified

The current version can be built from source, initialize a project, install a local DSH Profile and Codex Plugin, run health checks, and drive DSH through MCP to complete isolated Worktree tasks. Real Provider closed-loop evidence is stored in real-dsh-rc8.json, real-dsh-rc8.patch, and real-dsh-rc8-continue.patch.

The current release is source installation only; npm packages and Marketplace public releases have not been published. The first locked DSH compatibility baseline is 0.1.0-rc.8. DSH is in Developer Preview, so upgrading DSH must go through compatibility testing and cannot be inferred from the version number alone.

Related MCP server: agent-rack

What Problem Does It Solve?

When a task is not worth consuming the full context of the orchestrator model, Codex can hand it off to DSH:

Codex（计划 / 委派 / 审查）
        │
        │  Direct Mode：默认、低额外成本
        ▼
本地 MCP Gateway + Task Engine
        │
        ▼
DSH Plugin（Profile / 模型 / 工具 / Sub-Agent）
        │
        ▼
隔离 Worktree → Diff、测试、摘要、Artifact

Bridge does not claim DSH as a native Codex model or native Sub-Agent. The default Direct Mode is the Codex main thread calling Bridge MCP directly; the optional Native Shell Mode generates a narrow-responsibility Codex custom Agent as a scheduling shell for a closer-to-native-thread experience, but consumes additional Codex usage.

10-Minute Quickstart (Source Available)

Please use the source path for now; npm and Marketplace have not been published, so do not install a package with the same name from a public registry or directory.

Source Installation (Current Development Path)

Prerequisites: Node.js 22.19+ or 24+, pnpm, Git, a runnable DSH 0.1.0-rc.8, Codex CLI or Desktop, and at least one Provider already configured in DSH.

git clone https://github.com/HazenSun/dsh-codex-bridge.git
cd dsh-codex-bridge
corepack enable
pnpm install
pnpm build
pnpm dsh-bridge --help

Initialize, install, and health check:

BRIDGE_PROJECT=/absolute/path/to/your-project
pnpm dsh-bridge init "$BRIDGE_PROJECT" --mode direct
pnpm dsh-bridge install --source . --codex --dsh --mode direct
pnpm dsh-bridge doctor --config "$BRIDGE_PROJECT/bridge.yaml" --json --redacted
pnpm dsh-bridge profiles validate --config "$BRIDGE_PROJECT/bridge.yaml"

Then, in a new Codex session, call list_profiles, and then use delegate_task to delegate a read-only or small-scope implementation task. The default task uses an isolated Git Worktree; the main workspace should not be modified directly.

After installation, there is no need to memorize tool names. Just tell Codex:

使用 DSH 处理这个任务，自己判断单 Agent 还是多 Agent。

The delegate-to-dsh Skill discovers available Profiles, chooses single or multi based on the isolated workflow and review benefits, and writes the rationale and role into the task. Explicitly saying "single Agent" or "multi Agent" always overrides the automatic decision. Multi-Agent only passes if enough Sub-Agent calls and completion events are observed in the DSH Session.

Real DSH Closed-Loop Verification

This command starts a real DSH 0.1.0-rc.8 Profile and calls the Provider configured on the current machine; it is not a Fake LLM or offline simulation:

pnpm test:e2e:dsh
pnpm test:e2e:model-matrix

Corresponding evidence: real-dsh-rc8.json, real-dsh-rc8.patch, real-dsh-rc8-continue.patch, and model-matrix.json. DSH Provider configuration must be completed before running; the test produces real network/model calls and verifies task state, model routing, automatic single/multi-Agent decisions, Sub-Agent events, Artifact Hash, same-Session continuation, real cancellation, and an unchanged main workspace in a temporary Git Fixture.

Future Release Installation (npm / Marketplace)

The npm package and Codex Plugin Marketplace package are not yet published. Future package names, review status, Node runtime, and DSH version constraints are subject to the official Release Notes; do not run global installation commands for the current version that have not been confirmed by the release notes.

Two Operating Modes

Both modes share the protocol, Profile, task state, Worktree, and Artifact; switching modes should not change the task result format.

Documentation Navigation

• Full Installation Guide: environment, source build, Direct/Native Shell, upgrade and uninstall boundaries.

• Full Usage Guide: natural language triggers, single/multi Agent, Profile, result review, continue and cancel.

• 10-Minute Getting Started: from source installation to the first auditable task.

• Configuration Reference: Profile, model routing, workspace, concurrency, and policies.

• Technical Feasibility Report: public API evidence, boundaries, and M0 PoC.

• Software Architecture Plan: Gateway, Task Engine, DSH Adapter, and protocol.

• Implementation and Release Plan: milestones, tests, and Definition of Done.

• Security Model: keys, paths, network, shell, recursion, and artifact boundaries.

• Troubleshooting: doctor, MCP, DSH, Provider, Worktree, and recovery.

• Contribution Guide: local development, testing, changes, and Pull Request conventions.

• Security Vulnerability Disclosure: do not submit sensitive vulnerability details in public Issues.

• Code of Conduct: collaboration standards to maintain when participating in the project.

• Support Channels: where to go for bugs, feature suggestions, and security issues.

• Changelog: current Alpha features and known limitations.

Current Limitations

• Source installation only; npm packages and the public Codex Plugin Directory have not been published.

• The current write runtime only supports Git isolated Worktree.

• Bridge does not automatically commit, merge, deploy, or publish DSH results.

• Some network, denial paths, file count, and disk policies in the Profile are still protocol declarations and have not all been mapped to Bridge-side executors.

• Deterministic cross-model execution should use multiple named Profiles; role-level sub-model enforcement routing still requires the DSH Child Setup Contract.

Design Commitments

• Protocol first: Codex, DSH, and other future Hosts only exchange versioned JSON, never exposing Cordis private types.

• Profile over model: users choose semantic Profiles; Provider, Model, and Reasoning are verifiable resolution results.

• Safety by default: isolated Worktree, least privilege, resource limits, cancellable, and secret redaction by default.

• Codex owns the decision: DSH returns evidence; Codex decides to accept, continue, cancel, or abandon.

• Release as one unit: Codex Plugin, DSH Plugin, and the shared protocol are released together with fixed versions.

Open Source License

The code is licensed under Apache-2.0. Third-party dependencies, examples, and DSH itself retain their respective copyrights and licenses; a dependency license list, SBOM, and build provenance will be generated before the official release.

Contributions and Feedback

The project has a reproducible source closed loop. Before submitting an Issue, please read the Contribution Guide and Troubleshooting; for security issues, follow SECURITY.md and do not paste keys, cookies, full logs, or private code into public Issues.