Skip to main content
Glama

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.

CI License Node.js Platform

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.

Related MCP server: dsh-mcp-server

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.

Available Tools

12 tools
zcode_cancelCancel a queued or running ZCode taskA

Cancel a queued or running task. Running cancellation returns only after the worker process tree termination is confirmed. Results describe Bridge/ZCode execution only: status 'completed' means the invocation and report normalization finished, NOT that the calling host accepted the work. the calling host must independently review the workspace diff and checks before deciding PASS.

Inputs: task_id (required). Returns: error, status, attempt, task_id, +8 more

zcode_clear_default_modelClear the Bridge default modelA

Remove the Bridge default model so future tasks without zcode_task.model use the ZCode session default.

Inputs: no named parameters. Returns: model, configured

zcode_continueContinue a ZCode task with master feedbackA

Continue a finished task with master feedback: reuses the task ID and workspace, increments the attempt, and preserves prior evidence. Allowed from completed, failed, or waiting_for_master. Supply a stable operation_id when retrying after a lost response; the same ID and input will not create another attempt. A decision flagged by ZCode is never auto-approved; the calling host must provide the follow-up instruction. Results describe Bridge/ZCode execution only: status 'completed' means the invocation and report normalization finished, NOT that the calling host accepted the work. the calling host must independently review the workspace diff and checks before deciding PASS.

Inputs: task_id (required), feedback (required), operation_id, additional_requirements. Returns: status, task_id, created_at

zcode_default_modelRead the Bridge default modelA

Read the provider, model, and optional reasoning level used when zcode_task has no model override.

Inputs: no named parameters. Returns: model, configured

zcode_doctorCheck ZCode Bridge setupA

Run read-only checks for Bridge prerequisites, ZCode runtime/provider configuration, execution mode, task storage, and Desktop task-index availability. It does not start a ZCode session. App-server model availability and real permission approval are reported as unverified until a task runs.

Inputs: no named parameters. Returns: checks, checked_at, execution_mode

zcode_eventsRead live ZCode execution eventsA

Read persisted progress events for a task. Set view to summary to merge adjacent model text chunks; raw is the default. next_seq advances across all scanned events, including merged chunks. Immediately after submission, report the project path, effective execution path (and worktree path when supplied), and queued/running state from the first events. Keep polling until turn_started or startup failure; before longer monitoring, report the ZCode session, runtime-reported selected model, runtime-reported reasoning level when present, and execution mode. Set after_seq to the last next_seq returned and wait_ms up to 25000. Hidden reasoning is excluded. interaction_requested events include bounded tool/request details needed for a deliberate permission or input decision.

Inputs: task_id (required), view, limit, wait_ms, +1 more. Returns: events, status, task_id, has_more, +2 more

zcode_interaction_replyReply to a ZCode permission or input requestA

Reply to a pending ZCode permission or user-input request surfaced by zcode_events. For permission requests, use allow only when the user explicitly authorized the requested action; otherwise deny or ask the user. Do not infer permission from task instructions, worktree use, or ZCode mode. For user-input requests, answer only from known facts or the user's explicit direction. This tool does not approve the task result.

Inputs: task_id (required), decision (required), request_id (required), reason, +1 more.

zcode_model_catalogRead available ZCode modelsA

Read models and reasoning levels for this workspace. The Bridge caches the catalog for 24 hours, refreshes when provider settings change or the cache expires, and re-reads provider config before retrying a failed refresh. A cache response has current_model=null; use provider_id/model_id from models in zcode_task.model.

Inputs: workspace (required). Returns: models, warning, cached_at, workspace, +3 more

zcode_resultRead the terminal ZCode task resultA

Read the persisted TaskResult for a finished task. Returns TASK_NOT_FINISHED before a terminal state. 'completed' is not a the calling host PASS: files_changed, tests, and decisions are normalized claims from the subordinate report and must be verified independently. Results describe Bridge/ZCode execution only: status 'completed' means the invocation and report normalization finished, NOT that the calling host accepted the work. the calling host must independently review the workspace diff and checks before deciding PASS.

Inputs: task_id (required). Returns: tests, issues, status, attempt, +11 more

zcode_set_default_modelSet the Bridge default modelA

Persist a default provider/model selection for future tasks that omit zcode_task.model. Use IDs from zcode_model_catalog or the configured ZCode provider/model rules; the app-server validates the selection when a task starts. An optional reasoning_level applies to the configured default model; a per-task model selection can still override it.

Inputs: model_id (required), provider_id (required), reasoning_level. Returns: model, configured

zcode_statusRead ZCode task execution statusA

Read the execution status record for one task. This is execution status only and never contains a PASS/FAIL code-review judgment. Results describe Bridge/ZCode execution only: status 'completed' means the invocation and report normalization finished, NOT that the calling host accepted the work. the calling host must independently review the workspace diff and checks before deciding PASS.

Inputs: task_id (required). Returns: error, status, attempt, task_id, +8 more

zcode_taskSubmit one ZCode coding taskA

Create a bounded coding task for the local ZCode subordinate agent. workspace is the the calling host project root and determines the ZCode Desktop project identity. the calling host decides whether to create a worktree; if it does, pass its existing absolute directory as optional worktree_path. The Bridge never creates, selects, or removes a worktree. Without worktree_path, ZCode runs directly in workspace. Optional model selects a ZCode provider_id/model_id for this session without changing the project default. Returns a TaskReceipt; the task runs asynchronously in a detached worker. Results describe Bridge/ZCode execution only: status 'completed' means the invocation and report normalization finished, NOT that the calling host accepted the work. the calling host must independently review the workspace diff and checks before deciding PASS.

Inputs: task_id (required), objective (required), workspace (required), requirements (required), +8 more. Returns: status, task_id, created_at

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: task creation, cancellation, continuation, and interaction replies are unambiguous. However, zcode_status, zcode_result, and zcode_events are three separate read tools over task state, and zcode_default_model vs zcode_model_catalog could momentarily overlap, though the descriptions do distinguish them.

    Naming Consistency4/5

    All tools share a consistent zcode_ prefix and snake_case, which makes the set predictable. The minor deviation is that some names are nouns (zcode_task, zcode_status, zcode_result) while others are verb-led (zcode_continue, zcode_cancel, zcode_set_default_model), so the pattern is readable but not a strict verb_noun convention.

    Tool Count5/5

    Twelve tools is well within a sensible range and each earns its place, covering task lifecycle, event streaming, interaction handling, model configuration, and diagnostics without redundancy.

    Completeness4/5

    The surface covers the full task lifecycle (create, status, result, continue, cancel), event streaming, permission/input replies, model default read/set/clear, catalog, and a doctor diagnostic. A minor gap exists, such as no explicit task listing or deletion/cleanup operation, but core workflows are covered.

    Maintenance

    ActivityNo data
    ResponsivenessSyncing

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Exposes DeepSeek Harness agent capabilities as an MCP server, letting any MCP client drive Harness to execute real coding tasks with structured results, context isolation, and parallel execution.
      80 npm
      15
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables programmatic control of the Z.ai/Zhipu desktop AI coding agent by spawning and owning its headless agent runtime and speaking the ZCode Protocol over stdio, rather than simulating a user. Exposes tools to run and steer chat sessions, inspect conversations and file changes/rewinds, and manage settings, providers, plugins, MCP servers, automations and approvals under a deny-by-default policy with mandatory read-back verification.
      14
      2
      MIT