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

Variable	Description	Default
DSH_BATCH_CONTROLLER	Absolute path to the isolated-worktree controller	(required)
DSH_COMMAND	dsh, or an absolute DSH JavaScript launcher module passed safely to the controller	dsh
DSH_TIMEOUT_MS	Default timeout for delegated tasks; clamped 10 s – 2 h	1800000 (30 min)
DSH_MAX_OUTPUT_CHARS	Max chars returned to Codex context	6000
DEEPSEEK_ALLOWED_ROOT	Optional root; restricts which directories DeepSeek can access	(none)

Auto-retry

Variable	Description	Default
DSH_AUTO_RETRY	Whether to auto-retry on transient failures	true
DSH_MAX_RETRIES	Max retries (beyond initial attempt, so 1 = 2 attempts total)	1

Statistics

Variable	Description	Default
DSH_STATS_ENABLED	Enable stats persistence	true
DSH_STATS_FILE	Path to stats file; absolute or relative to workspace	.codex-deepseek/stats.json
DSH_TOKEN_STATS	Enable token usage tracking	true

Result format

Every delegation tool returns a compact structured JSON object with:

Field	Description
status	success, failed, or escalated_to_codex
tool	The tool name (e.g. deepseek_task)
task_id	Unique ID: ds_YYYYMMDD_shortid
attempt	Current attempt number
attempts	Actual number of attempts completed
max_attempts	Configured maximum (initial + retries)
duration_ms	Wall-clock duration of this attempt
exit_code	Exit code from the batch controller
changed_files	Array of file paths that were changed
tests	{ ran, passed, summary }
usage	Token usage with source (reported/estimated) and estimated boolean
summary	Short description of what was done
artifact_paths	{ run_dir, report, patch }
failure_type	timeout, controller_error, malformed_output, unable_to_complete, test_failure, no_changes, or null
retry_recommended	Whether this failure type qualifies for retry
will_retry	Whether another attempt will actually run under the configured limit
escalated	Boolean; true when all attempts exhausted
escalation_marker	"ESCALATED_TO_CODEX" when exhausted

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.