dsh_agentlink
Connect-only MCP bridge that lets Codex delegate, supervise, and continue bounded work on a user-managed DeepSeek Harness (DSH) Host, with human-gated approvals.
Check DSH Host connection state and capabilities.
Discover existing root sessions, attach an exact idle session, and continue the same task.
Delegate a scoped prompt to a new DSH root session and optionally select model route or reasoning effort.
Monitor status, event tails, waits/observations, queue state, and final answers.
Cancel a turn or queued work and list mapped tasks.
Answer typed DSH questions and resolve sandbox-escalation approvals only with human approval.
Maintain or release bridge-local cooperative workspace claims, without enforcing DSH filesystem permissions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@dsh_agentlink delegate this failing test to DSH and summarize the suspected root cause"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Codex-DSH-Orchestrator
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 |
|
Official Gateway at a known origin |
|
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.
Recommended: copy/paste the Agent installation prompt
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 checkFor official Desktop on Windows or macOS, preview the configuration:
npm run setup -- --yes --gateway --desktop-auto --no-preset --dry-runThe 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-presetSetup 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 | Verify the session's current route; no model-selection write |
| Select an advertised official route on the current account/API-key provider |
| Require that exact effort in the current catalog |
Visual low complexity |
|
Visual high complexity | Ask the user to choose |
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 |
| Connection state and capabilities |
| Bounded root-session metadata discovery |
| Attach an exact idle root with fresh preconditions |
| Create a root and queue its initial prompt |
| Continue that root; queue or steer |
| Execution, pending interactions, final answer and workspace claim semantics |
| Bounded event digests and next cursor |
| Bounded observation; one window is at most 30 seconds |
| Cancel the current turn or observed queue items |
| List mapped tasks |
| Answer a typed pending question |
| Human-approved |
| 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/projectThat 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
src/: shared MCP runtime and setup.skill/codex-dsh-orchestrator/: canonical Codex Skill; edit this source, not an installed copy.skill/codex-dsh/andskill/claude-code-dsh/: compatibility Skills.test/: synthetic Host, protocol, persistence and install regressions.Project overview, Architecture, Validation, Manual configuration, Release checklist, Contributing and Security.
Related projects
Project | Relationship |
Official Desktop and Host runtime | |
Community client, retained Windows legacy discovery | |
Optional vision plugin. Not maintained by or affiliated with this project | |
Caller-to-bridge protocol | |
Upstream MIT code and compatibility lineage |
License
MIT. Read Known issues before upgrading a shared bridge home.
Available Tools
15 toolsdsh_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_cancelADestructive
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_sessionsARead-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_statusARead-onlyIdempotent
Report the connect-only bridge state and current official DSH Web Host capabilities.
Inputs: no named parameters.
dsh_listARead-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_observeBRead-onlyIdempotent
Compatibility observation alias. Prefer dsh_wait plus dsh_tail task cursors.
Inputs: taskId (required), afterCursor, waitSeconds.
dsh_release_workspaceADestructive
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_approvalADestructive
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_statusBRead-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_tailBRead-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_waitARead-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
Scored across 15 tools
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 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.
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.
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
Related MCP Connectors
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Capture coding-agent sessions and resume them in any other agent: Claude Code, Codex, Cursor, more.
No-data MCP handoff for local Claude Code to Codex harness moves. $49 lifetime.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables dispatching work to DeepSeek Harness agents from Claude Code/Codex, with native progress UI, tier policy, and vision/image generation through MCP tools.815 npm215MIT
- AlicenseNot gradedqualityBmaintenanceEnables Codex to delegate coding tasks to a persistent DeepSeek Harness agent that can read repositories, edit files, and run tests, while letting users follow up, monitor progress, and interrupt the work.101 npm4MIT
- AlicenseNot gradedqualityCmaintenanceEnables Codex to delegate tasks to DeepSeek Harness through A2A/ACP, with reusable conversation contexts and a local dashboard for task status.1MIT
- AlicenseNot gradedqualityAmaintenanceEnables Claude Code, Codex, Antigravity and Grok to dispatch tasks to DeepSeek Harness agents as native subagents with live progress, tier and effort presets, workspace guardrails, a jobs board, and a vision/image-generation bridge for text-only models.354 npmMIT