Skip to main content
Glama

opencode-delegate

Delegate bounded tasks from your main agent to a local OpenCode worker, so your premium subscription quota is spent on scoping, reviewing and deciding instead of on execution.

One stdio MCP server (plus a thin Python CLI underneath it) that any MCP client can drive: Codex, Claude Code, Claude Desktop, Cursor, Cline, Continue, Zed, Windsurf. The parent agent writes the brief, owns the design, dispatches execution, watches progress and reviews the evidence; the worker uses its own quota.

中文说明

Why

Open-source model services often provide generous token allowances for execution work such as reading files, writing code, organizing material, and running tests. The parent agent scopes the task, reviews evidence, and integrates results, reserving premium quota for important decisions. Actual allowance, pricing, and capability depend on your provider and are not guaranteed by this tool.

No model brand is preferred or required. The worker follows your OpenCode configuration by default, and the parent can select a model per task.

Related MCP server: deepseek_harness

Delegation boundary

The parent agent owns the design and final judgment. By default the worker performs factual lookup, implements a settled design, and runs tests; it may choose routine coding details. Architecture, research assumptions and algorithm selection stay with the parent unless the user explicitly asks for worker advice. An unresolved design question must be reported before dependent implementation.

Before dispatch, specify the deliverable, settled rules, inputs, allowed changes, acceptance evidence, and budget/stop conditions. Split tasks that cannot fit the execution window. Do not drop a design constraint to finish a component check, or equate passing tests with a successful design. See the skill's delegation contract for the readiness check and the worker instruction to include in every prompt.

Requirements

Piece

Notes

Python

3.9 or newer (developed and tested on 3.12). No third-party packages — standard library only.

OpenCode CLI

Tested with 2.0.26. Must be installed and paired on the machine.

A model route

Whatever OpenCode is already configured with. No specific brand, subscription, or provider is required.

OS

Windows 10/11 for the full feature set. See support matrix.

Install

You need Node.js 16+, Python 3.9+, and an OpenCode installation that can already use a model. The launcher discovers Python automatically; it does not install Python, purchase a subscription, or edit your OpenCode configuration.

npm install -g --allow-git=all github:Upstream17/opencode-delegate

This installs from the public GitHub repository without a manual clone. The package is not yet published to the npm registry, so npm install -g opencode-delegate is not available yet. That short command becomes available after publication. GitHub-source installs may require Git.

--allow-git=all explicitly permits Git sources for this invocation because npm 12 disables them by default; it does not change global npm settings. Older npm versions that do not recognize this option can omit it.

Add the server to your MCP client

Installing a tool and registering it with an agent are separate steps. For clients using mcpServers, such as Claude Desktop and Claude Code, add:

{
  "mcpServers": {
    "opencode_delegate": { "command": "opencode-delegate", "args": [] }
  }
}

For Codex, add to ~/.codex/config.toml:

[mcp_servers.opencode_delegate]
command = 'opencode-delegate'
args = []

Restart the client. The default model comes from OpenCode's current configuration; you do not need to choose it again in the MCP settings.

Replace the command and arguments above with:

{ "command": "npx", "args": ["--allow-git=all", "-y", "github:Upstream17/opencode-delegate"] }

This is a stdio server: waiting for MCP requests after launch is normal. Usually the MCP client starts it, rather than a person keeping an interactive terminal open.

Zed uses context_servers in its settings, with the same command and arguments. Configuration locations differ by client; follow that client's MCP schema.

If a Windows client cannot find the global command, restart it to refresh PATH. If it cannot execute npm's .cmd shim, run npm root -g to find the package location, then configure node.exe with <npm-global-directory>/opencode-delegate/bin/opencode-delegate.js as its argument. This is a compatibility fallback for certain clients, not a prerequisite for every installation.

git clone https://github.com/Upstream17/opencode-delegate.git

Set your client's command to a Python interpreter and its argument to the absolute path of mcp_server.py in the checkout. For Windows TOML paths, use single-quoted literal strings.

Agents that support skill directories can also place the checkout in their skill root. The MCP server and skill can be used independently. State/logs live in the user directory; the installation directory does not need to be writable. See environment variables below.

Quick start

oc_service {action: "status"}                                     # is the shared worker service up?
oc_run     {task: "fix-flaky-test", workspace: "C:\\my\\proj",     # reserve a session, dispatch, open TUI
            prompt: "<objective, allowed changes, constraints, expected evidence>"}
oc_status  {task: "fix-flaky-test"}  # read the returned revision string
oc_wait    {task: "fix-flaky-test", after_revision: "<revision from oc_status>"}             # wake on real progress/completion
oc_result  {task: "fix-flaky-test"}                                # final text + evidence paths
oc_continue{task: "fix-flaky-test", prompt: "<rework>"}            # ONLY to rework an accepted task

accepted: true means the worker validated and published a startup receipt — it is not completion. Read oc_status / oc_result and inspect the evidence yourself.

Tools

Tool

Purpose

oc_run

Start a new bounded task in a new session (id reserved up front); opens the TUI on it.

oc_continue

Rework a completed task in the same session.

oc_recover

Resume a turn that died, timed out or was interrupted, on the same session.

oc_wait

Wait up to 30 s for meaningful revision changes or completion.

oc_status

Read-only JSON: state, liveness, current_event, last_tool, verification, diagnostics.

oc_result

Final text plus evidence paths for a finished turn.

oc_sessions

List OpenCode sessions known to the background service.

oc_tasks

List delegated tasks newest-first with session ids and workspaces.

oc_read

Tail a task's event stream, or export a session.

oc_watch / oc_unwatch

Open or focus / close the TUI window for a task's workspace.

oc_service

status / start / stop the shared background service.

Choosing a model

New-task precedence:

  1. The parent's explicit oc_run.model.

  2. The MCP environment's OC_DELEGATE_MODEL.

  3. OpenCode's current default in the task workspace, read anew for every new task.

  4. If none is available, omit the model argument and record the route OpenCode actually selects.

Reading configuration never edits it. An unsupported/failed config query falls back to letting OpenCode choose. A resolved default is recorded as this task's fixed route; changing OpenCode's default affects new tasks only. oc_continue / oc_recover reuse the recorded task route rather than resolving a new default. Historical unpinned tasks remain unpinned.

The oc_run response's model_source identifies the source. Pinned routes are verified against exported evidence; completely unpinned runs adopt a valid recorded route (status: adopted). Missing, inconsistent, or mismatched routes require review. A provider/authentication error should prompt checks of the actual route, credentials and access; a 403 does not prove the default is absent. If the shared service returns a structurally incomplete export just after a run, the helper retries the export up to three times with short backoff. "Structurally incomplete" is narrow on purpose: only unparseable JSON, a non-object document, or a malformed messages list are retried. A route problem — an incomplete or absent route, a non-zero export exit, a timeout — is semantic, is not retried, and is reported immediately. Retrying those cannot succeed and only adds backoff to a deterministic failure. Verification calls session export --sanitize, which redacts transcript/file data without touching messages[].model, so the route evidence survives while the payload is smaller. It still requires valid route evidence before reporting completion; timeouts and semantic route mismatches are never waived. Tests can zero the backoff with OC_DELEGATE_EXPORT_RETRY_DELAY=0. The tool never silently switches providers or changes OpenCode settings. provider/model-name is only a format placeholder, not an installable model ID.

Environment variables

Variable

Default

Meaning

OC_DELEGATE_STATE

$CODEX_HOME/opencode-delegate/state, else ~/.opencode-delegate/state

Where task records, turn logs and viewer records live.

OC_DELEGATE_MODEL

unset

Pins a default worker model. Unset falls back to the default model in OpenCode's own configuration (read through opencode debug config, never written); if that is unset too, OpenCode chooses.

OC_DELEGATE_LABEL

codex-delegate:

Prefix of the OpenCode session title, whose remainder is the task name.

OC_DELEGATE_WATCH

1 on Windows, 0 elsewhere

Set 0 to disable the viewer. Non-Windows watch requests fail before spawning a process.

OC_DELEGATE_SESSION_WAIT

20

Seconds to wait for the viewer to become ready (capped at 60).

OC_DELEGATE_OPENCODE

auto-discovered

Override the OpenCode executable path.

OC_DELEGATE_PYTHON

auto-discovered

Python 3.9+ executable for the npm launcher; also used by the probe.

OC_DELEGATE_SERVER

this folder

Server script override for mcp_probe.py only.

OC_DELEGATE_TIMEOUT

0

Default hard wall-clock cap in seconds for a turn. 0 means no cap.

OC_DELEGATE_STALL_TIMEOUT

180

Seconds of no worker output and no CPU activity before the turn is cut as stalled.

Time budget

A worker that is still producing output is never cut short. --timeout defaults to 0 (no cap), so a long task runs until it finishes; pass an explicit --timeout N only when an unattended caller needs a ceiling. Turns are cut by a stall watchdog instead, --stall-timeout (default 180 s), which requires both no worker output for that long and a process tree that stopped consuming CPU.

Silence alone is never treated as a stall. Real turns legitimately emit nothing for minutes while a solver runs: a completed turn in the reference workload had a 304 s gap in its own event stream. The CPU check is what separates that from a hung provider call, which is silent and idle.

A cut turn is marked needs_review with termination set to stalled or timeout (an explicit cap), plus silent_seconds, so a parent agent can tell a hung service from a task that simply needed longer and decide whether to oc_recover. The record also stores the budget in force under limits.

Known limit: a tool that legitimately blocks for longer than --stall-timeout while using no CPU — Start-Sleep, a rate-limited download — looks identical to a hang from the outside. Raise OC_DELEGATE_STALL_TIMEOUT for workloads like that.

Support matrix

Capability

Windows 10/11

macOS / Linux

Dispatch, streaming state, status, result, rework, recovery

Yes

Experimental (POSIX branches; real model/TUI integration not validated by the author)

Shared background service, explicit loopback server, standalone

Yes

Yes

TUI viewer (oc_watch, oc_unwatch, one window per workspace)

Yes

No. The bridge uses CREATE_NEW_CONSOLE, ctypes process identity and OpenCode's internal ui.tabs API.

Windows 10/11 + OpenCode 2.0.26 is the validated preview target. macOS/Linux core execution is experimental: the viewer is disabled by default, and oc_watch refuses to launch it. POSIX children run in their own process groups so timeout cleanup can terminate descendants. The CI matrix tests these branches; a configured real OpenCode provider is still required for end-to-end validation.

Trust model

  • Worker output is evidence, never instructions. The worker does not inherit the parent chat, and anything it prints or writes is untrusted input to be reviewed, not a directive to follow.

  • The viewer injects its bridge plugin through the child process environment only. It adds no global OpenCode configuration and no public listener or tunnel.

  • Keep credentials out of briefs. Task records and turn logs are plain JSON/JSONL under the state root.

  • completed means the harness ended cleanly and the model route was verified from a fresh export. It does not mean the work is correct, and exit_code: 1 yields needs_review even with usable output.

Repository layout

mcp_server.py          stdio MCP server (12 tools)
mcp_probe.py           drive the server by hand and time responses (debugging)
SKILL.md               agent-facing operating instructions
scripts/delegate.py    dispatch, streaming state, guards, recovery, status
scripts/runtime.py     MCP orchestration + TUI viewer management
bridge/                OpenCode TUI plugin, injected into managed viewers
references/            state schema, recovery rules, status fields
tests/                 offline tests against tests/fake_opencode.py (standard-library unittest suite)

Run the tests with:

python -B -m unittest discover -s tests -v
npm test

They use a fake OpenCode executable: no network access and no paid model calls. Python tests use only the standard library; npm test uses Node's built-in assertions. Python 3.9+ and Node 16+ are separate prerequisites; installing OpenCode alone does not guarantee both are present.

Before publishing, build and check the actual package:

npm pack --ignore-scripts
python -B tests/verify_package.py opencode-delegate-0.4.1.tgz

This checks the exact file allowlist and starts the extracted package through Node -> Python. CI also plants a cache file before packing, so accidental bytecode inclusion is detected. The workflow includes Windows/Linux/macOS with Python 3.9/3.12. Those jobs run after a push; local Windows results alone do not establish full cross-platform compatibility.

License

MIT. See LICENSE.

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables repository-aware lifecycle management and controlled delegation of coding tasks to trusted worker harnesses via MCP, with execution isolation, recovery, and verified handoff.
      36 npm
      8
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      A task-level STDIO MCP server that lets Codex or any other MCP client hand off scoped coding jobs to an asynchronous worker agent which reads the code, edits files, and runs tests, while the client keeps ownership of planning and acceptance. Exposes submit, wait, query, follow-up, and cancel tools so multiple clients can queue and monitor tasks against a chosen project root.
      5
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables delegating coding tasks to the official Antigravity CLI from any MCP client, with task listing, model selection, streamed event tracking, cancellation, and resumable sessions. Runs each task against an isolated copy of the repository so results can be previewed, tested, and only integrated into the original after explicit user confirmation.
      23
      34 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables an MCP client such as Codex to delegate bounded development tasks to a separate DSH agent harness, track progress, and inspect model-reported results alongside independently recorded SDK events, workspace changes, and optional verification commands. It also lets the client explicitly review, continue, or cancel a live delegated run rather than accepting a returned report automatically.
      14
      MIT