Codex DSH MCP

A cost-aware MCP bridge that lets Codex delegate routine, context-heavy work to DeepSeek Harness—while Codex keeps architecture, review, and final verification under control.

Codex DSH MCP runs each DeepSeek worker in an isolated Git worktree created from committed HEAD. It never applies changes to the main workspace automatically: Codex and the human reviewer receive a compact result, a Markdown report, and a patch to inspect first.

Why use it?

• Offload repository exploration, routine implementation, refactors, tests, and ordinary fixes to DeepSeek.

• Keep high-risk architecture, security, final review, and acceptance with Codex.

• Retry a failed delegation at most once, then return ESCALATED_TO_CODEX instead of wasting calls.

• Track calls, duration, success rate, and clearly labeled estimated/reported token usage per project.

• Keep the main checkout protected: workers operate only in isolated worktrees.

Quick start

1. Clone this repository and open its folder in Windows Explorer.

2. Double-click install-windows.bat (or run install-windows.ps1 in PowerShell).

3. Merge config.toml.example into %USERPROFILE%\.codex\config.toml and update the bridge path.

4. Merge AGENTS.md into your global or project-level Codex instructions.

5. Restart Codex and confirm the deepseek MCP server exposes five tools.

What it exposes

• deepseek_explore — read-only repository exploration/search.

• deepseek_task — normal implementation/refactor/test work in an isolated worktree.

• deepseek_fix — bug/failing-test diagnose-edit-test loop in an isolated worktree.

• deepseek_review — read-only focused review.

• deepseek_stats — read-only bridge statistics (totals, tool counts, success rate, average duration, last 10 task metadata).

How routing works

AGENTS.md tells Codex to choose DIRECT_CODEX for small, critical, architectural, security-sensitive, destructive, or already-escalated work. It chooses DELEGATE_DEEPSEEK for broad exploration and routine work—especially when more than about three files must be read, more than about two files changed, or an edit/test/fix loop is likely. Codex does not scan the repository first just to make this choice.

User
 ↓
Codex Router
 ├── Small / Critical ──→ Codex
 │
 └── Delegatable
       ↓
    DeepSeek
       ↓
 ┌─────┴─────┐
Success     Failure
 ↓             ↓
Review      Retry once
               ↓
          Failure again
               ↓
             Codex

The retry is a focused bug-fix attempt using the same task ID. A second failure returns ESCALATED_TO_CODEX; Codex takes over and must not delegate that same problem a third time.

Requirements

• Windows 10/11 (the bridge also has a POSIX path).

• Node.js 20+.

• Codex with MCP support.

• DeepSeek Harness available as dsh and already configured/authenticated for the DeepSeek model/service you intend to use.

Install on Windows

Open PowerShell in this folder:

Set-ExecutionPolicy -Scope Process Bypass
.\install-windows.ps1

Or double-click install-windows.bat; it is a thin Windows wrapper around the same installer.

Then verify DeepSeek Harness independently before involving Codex:

dsh --profile headless "Reply with exactly READY"

If that does not work, fix dsh first. The MCP bridge intentionally does not manage DeepSeek credentials itself.

Configure Codex

Merge config.toml.example into %USERPROFILE%\.codex\config.toml, and replace the example path:

[mcp_servers.deepseek]
command = "node"
args = ["C:/tools/codex-deepseek-bridge/src/index.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 7200

[mcp_servers.deepseek.env]
DSH_BATCH_CONTROLLER = "C:/Users/Administrator/.codex/skills/dsh-batch-subagents/scripts/dsh-batch-agents.mjs"
DSH_COMMAND = "dsh"
DSH_TIMEOUT_MS = "1800000"
DSH_MAX_OUTPUT_CHARS = "6000"
DSH_AUTO_RETRY = "true"
DSH_MAX_RETRIES = "1"
DSH_STATS_ENABLED = "true"
DSH_TOKEN_STATS = "true"
DEEPSEEK_ALLOWED_ROOT = "D:/Projects"

Restart Codex. In Codex TUI, /mcp should show the deepseek MCP server and five tools.

Install the delegation prompt

For one repository, put AGENTS.md at the repository root (or merge the DeepSeek delegation section into an existing AGENTS.md).

For a global personal policy, merge the contents into %USERPROFILE%\.codex\AGENTS.md. Project-specific instructions can still override it.

Suggested first test

In a disposable Git repository, ask Codex:

Find where the CLI arguments are parsed. Use DeepSeek for repository exploration and report the relevant files. Do not modify anything.

Then try a harmless write task:

Add a small unit test for an existing pure helper. Delegate the implementation to DeepSeek, then inspect the diff and run the focused test yourself before reporting success.

Then verify stats:

Run deepseek_stats to check bridge usage and token savings.

Environment variables

Core

Auto-retry

Statistics

Result format

Every delegation tool returns a compact structured JSON object with:

Escalation flow

Tool call → attempt 1 (fails) → retry → attempt 2 (fails) → return escalated_to_codex

When a delegation returns status: "escalated_to_codex", Codex should investigate the root cause and decide on next steps. The bridge never calls the Codex API.

Token Statistics

Token usage is parsed from DeepSeek/Harness output when a usage JSON block is available (source: "reported", estimated: false). Otherwise, it is approximated from prompt/result character counts at about one token per four characters (source: "estimated", estimated: true). Reported usage is provider data; estimated usage is only a fallback approximation.

The project-level .codex-deepseek/stats.json records bounded metadata for at most 100 attempts and is written through a temporary file followed by rename. It never stores the complete task Prompt, result summary, diff, changed-file paths, or artifact paths. deepseek_stats returns totals, success rate, average duration, per-tool counts, and the most recent 10 metadata entries.

estimated_codex_tokens_avoided uses the amount of context handled by DeepSeek as a rough proxy for context Codex did not have to process. It is always marked estimate_only: true. It is not an OpenAI or Codex quota measurement and should be used only to judge whether delegation is directionally worthwhile.

Security model

deepseek_task and deepseek_fix allow DeepSeek Harness to edit only an isolated Git worktree. Reports and patches are kept outside the repository for Codex and human review. Nothing is merged or applied automatically.

deepseek_explore and deepseek_review also run in isolated worktrees. Their read-only behavior remains a prompt-level policy, but accidental writes cannot touch the main workspace.

deepseek_stats is read-only and accesses only the stats file.

Why this saves Codex usage

The expensive loop is usually repository search → many file reads → implementation → tests → failure analysis → retry. The bridge moves that loop into a separate DeepSeek Harness session. Only DeepSeek's compact structured result returns to Codex; Codex can then inspect the resulting diff and perform targeted verification.

Author

Created and maintained by @sakurameishi.

License

MIT © 2026 sakurameishi.