dsh-zcode-bridge

Use ZCode as a coding worker inside DeepSeek Harness (dsh).

Delegate coding tasks from your dsh agent to the local ZCode Agent. The dsh agent assigns tasks, monitors progress, reviews the resulting changes, and decides whether to accept the work or send it back for another iteration.

dsh delegates. ZCode codes. dsh reviews.

Forked from codex-zcode-bridge (a Codex plugin); the shared Bridge core is pinned as a dependency and delivered as a DeepSeek Harness bundle. See Fork notes.

English · 简体中文

---

How it works

You
 │  "Implement this feature."
 ▼
dsh agent ── delegates task ──▶ dsh-zcode-bridge ── starts / monitors ──▶ ZCode Agent
 ▲                                                                          │
 └────────── reviews diff, verifies, accepts or continues ◀── reports ──────┘

The dsh agent remains responsible for task definition, architecture, review, and acceptance. ZCode handles bounded implementation work in the local development environment. The bundle connects them through an MCP server (registered via the shipped @deepseek-ai/dsh-mcp-client) and ZCode's local runtime.

MCP tools appear as mcp__zcode_bridge__zcode_task, mcp__zcode_bridge__zcode_events, mcp__zcode_bridge__zcode_result, and the other zcode_* tools. The server also publishes MCP instructions describing the delegation flow and review discipline.

Features

• Submit, follow, continue, and cancel ZCode tasks from dsh.
• Run tasks across multiple projects concurrently; tasks sharing an execution directory are queued.
• Read the live ZCode model catalog and reasoning levels, select a provider/model per task, and get/set/clear a Bridge default model.
• At startup, report the project directory, execution directory, ZCode session, runtime-reported model and reasoning level, and execution mode.
• Group ZCode Desktop tasks under the delegating project directory; index sync failures do not stop task execution.

Install

Requires Node.js 22.18+, Git, ZCode installed and signed in, and DeepSeek Harness. Real ZCode E2E has only been completed on Windows; macOS and Linux have not been verified.

Install the bundle

1. Get the bundle directory plugins/dsh-zcode-bridge onto the machine running dsh (clone this repository, or download a release archive).
2. In a dsh session, call the plugin_manager tool with action: install_bundle and the absolute bundle directory as target (Creator mode can do this from a plain instruction such as "install the bundle at ").
3. After application: applied, verify the connection by calling mcp__zcode_bridge__zcode_doctor.

install_bundle copies the bundle into the profile's node_modules. The patch computes the server path from DSH_PROFILE_DIR, which every profile-launched Harness provides; if activation fails with "DSH_PROFILE_DIR is not set", launch dsh with a profile, or edit cordis.patch.yml to hard-code the absolute path to server/bridge.mjs. Tools appear to the model only after the MCP connection succeeds (failOnStartupError: true rejects activation on failure).

Install the delegation skill

The release bundle includes skills/zcode-bridge/SKILL.md. Copy it to %USERPROFILE%\.dsh\skills\zcode-bridge\SKILL.md (create the directory if needed) so dsh's filesystem skill provider can discover it. The MCP bundle itself cannot install a global user skill. Skill availability also depends on the active dsh profile exposing its skill provider and loader.

Configuration

Task data lives in %USERPROFILE%\.dsh\zcode-bridge\ (macOS/Linux: ~/.dsh/zcode-bridge/). Optional settings go in runtime-config.json inside that directory (create it manually if needed). Keep the discovered path fields and change only the values you need:

• ZCODE_BRIDGE_NODE: absolute path to Node.js (only needed when node is not on PATH).
• ZCODE_BRIDGE_ZCODE_CJS: absolute path to the ZCode runtime.
• ZCODE_BUILTIN_PROVIDER_CONFIG_FILE and ZCODE_PERSONAL_PROVIDER_CONFIG_FILE: absolute paths to the builtin and personal provider config files.
• ZCODE_HOME: absolute path to the actual .zcode data directory.
• ZCODE_BRIDGE_DATA_DIR: absolute path to the Bridge task data directory.
• ZCODE_BRIDGE_DEFAULT_PROVIDER_ID and ZCODE_BRIDGE_DEFAULT_MODEL_ID: default provider and model IDs; set both.
• ZCODE_BRIDGE_MODE: initial execution mode: plan, build, edit, or yolo; defaults to yolo. yolo allows ordinary tool operations with the current operating-system account's permissions. Set it to build to use ZCode's approval rules.
• ZCODE_BRIDGE_TIMEOUT_MS: default wall-clock limit for one task attempt when timeout_ms is omitted; 60,000–14,400,000 milliseconds, default 3,600,000 (60 minutes).
• ZCODE_BRIDGE_MAX_CONCURRENT_WORKERS: parallel task limit, 1–8, default 8.

ZCODE_HOME must point to the .zcode directory, and the personal provider config must be at v2/provider_config.json inside it. Copy provider/model IDs from your ZCode configuration, and do not edit ZCode's provider files.

Use

Describe the development task and its acceptance criteria. The dsh agent decides whether to prepare a worktree, then delegates the task to ZCode. ZCode runs in that worktree when provided, or directly in the project directory otherwise. ZCode does not automatically receive the full conversation, so the delegating agent must include any required project decisions and constraints with the task.

After execution, review the actual diff and run acceptance checks independently. completed means ZCode reported the task finished; it does not mean the changes are approved. If an unresolved decision could materially affect behavior, ZCode asks for direction before proceeding on that point.

In ZCode Desktop, find tasks in the Workspace view under the delegating project directory.

For installation or startup problems, call mcp__zcode_bridge__zcode_doctor for read-only setup diagnostics. Use zcode_model_catalog to read model IDs and reasoning levels, pass provider_id/model_id in zcode_task.model for one task, and manage the default with zcode_set_default_model / zcode_default_model / zcode_clear_default_model.

The zcode-bridge skill provides the full per-task delegation checklist; its reference text is docs/BRIDGE_WORKFLOW.zh-CN.md.

Known issues

• The ZCode Desktop sidebar may not immediately show a new session. The Bridge best-effort syncs the local task index; Desktop controls when the list refreshes.
• ZCode Start Plan is currently unavailable through the Bridge.
• A worker gets a 10-second cold-start grace window (workerStartGraceMs): within it, a missing or just-exited pid does not immediately finalize worker_lost; later reconcile ticks re-check. If a worker exits before writing started.json (it never ran the task), the Bridge respawns it once on the same attempt (a claim marker in the attempt directory prevents the Bridge processes sharing a data root from double-spawning); a worker that did start is never auto-respawned — the master decides whether to continue. Scheduling is serialized across Bridge processes sharing one data root. Separate data roots do not coordinate conflicting workspace writes.

Security and limitations

• The default execution mode is yolo. It allows ordinary tool operations with the current operating-system account's permissions; a worktree is not a sandbox. Set ZCODE_BRIDGE_MODE to build to use ZCode's approval rules. The Bridge has protocol tests for permission forwarding, but a real ZCode permission-approval roundtrip has not been verified.
• A Git worktree isolates the working directory; it is not an operating-system sandbox. allowed_paths and forbidden_paths describe task constraints but cannot prevent the process from accessing other files or running commands.
• The dsh agent decides whether to create a worktree. The Bridge uses the supplied project directory and optional worktree path; it does not create or remove worktrees.
• Parallel tasks use more local resources and provider capacity.
• The dsh-mcp-client scrubs credential-shaped ambient variables (KEY|PASSWORD|SECRET|TOKEN) and DSH_* names before spawning the Bridge; the Bridge needs none of them (ZCode reads its own provider config files). The Bridge stores prompts, status, logs, visible model output, events, and results locally in ~/.dsh/zcode-bridge/. Do not include data in tasks or workspaces if it should not be sent to the selected model service or persisted locally.
• The Bridge uses the local ZCode app-server. Interactions and available events depend on the installed ZCode version. For AskUserQuestion replies, key answers by each full questions[].question text and use the selected or explicit answer as its value; do not use the header or option label as the key. Only allow permission requests when the user explicitly authorizes the action.

Build from source

The repository includes TypeScript source for review and self-builds. With Node.js 22.18+:

npm ci
npm run build
npm run validate:bundle

The build writes the self-contained MCP server and worker into plugins/dsh-zcode-bridge/{server,worker}; both artifacts are committed so the bundle is installable without a build step.

Shared core provenance, host boundaries, configuration migration and upgrade steps are documented in docs/SHARED_CORE.md. The default tool set contains 12 stable tools; the experimental progress probe is disabled.

Fork notes

• Forked from codex-zcode-bridge at v1.0.0 and ported from a Codex marketplace plugin to a dsh bundle.
• Codex plugin surfaces (.codex-plugin, plugin.json, mcp.json, hooks/) were removed. The dsh bundle ships a standalone skill file for manual installation into dsh's user-level skill directory; first-run setup remains in zcode_doctor, tool descriptions, and MCP server instructions.
• Bridge data moved from ~/.codex/codex-zcode-bridge/ to ~/.dsh/zcode-bridge/; no data is migrated between them.
• The MCP server name is dsh-zcode-bridge; the dsh MCP server namespace is zcode_bridge.

Acknowledgements and license

Process handling is adapted in part from cc-plugin-codex; ZCode Desktop task-index integration is adapted in part from zcode-acp. Thanks to the MCP TypeScript SDK, Zod, the ZCode project, and the DeepSeek Harness team. See NOTICE for source and copyright details.

This project is licensed under Apache License 2.0. Third-party components remain subject to their respective licenses.