opencode-delegate
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.
Recommended: one npm install command
npm install -g --allow-git=all github:Upstream17/opencode-delegateThis 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.gitSet 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 taskaccepted: 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 |
| Start a new bounded task in a new session (id reserved up front); opens the TUI on it. |
| Rework a completed task in the same session. |
| Resume a turn that died, timed out or was interrupted, on the same session. |
| Wait up to 30 s for meaningful revision changes or completion. |
| Read-only JSON: state, liveness, |
| Final text plus evidence paths for a finished turn. |
| List OpenCode sessions known to the background service. |
| List delegated tasks newest-first with session ids and workspaces. |
| Tail a task's event stream, or export a session. |
| Open or focus / close the TUI window for a task's workspace. |
|
|
Choosing a model
New-task precedence:
The parent's explicit
oc_run.model.The MCP environment's
OC_DELEGATE_MODEL.OpenCode's current default in the task workspace, read anew for every new task.
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 |
|
| Where task records, turn logs and viewer records live. |
| unset | Pins a default worker model. Unset falls back to the default model in OpenCode's own configuration (read through |
|
| Prefix of the OpenCode session title, whose remainder is the task name. |
|
| Set |
|
| Seconds to wait for the viewer to become ready (capped at 60). |
| auto-discovered | Override the OpenCode executable path. |
| auto-discovered | Python 3.9+ executable for the npm launcher; also used by the probe. |
| this folder | Server script override for |
|
| Default hard wall-clock cap in seconds for a turn. |
|
| Seconds of no worker output and no CPU activity before the turn is cut as |
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 ( | Yes | No. The bridge uses |
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.
completedmeans the harness ended cleanly and the model route was verified from a fresh export. It does not mean the work is correct, andexit_code: 1yieldsneeds_revieweven 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 testThey 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.tgzThis 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP server for task-first delegation to remote workstations and workers.
Headless task management for bots, apps and AI agents. Remote MCP server, OAuth or access token.
Start and manage Reason cloud coding agents, projects and sessions from any MCP client.
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables repository-aware lifecycle management and controlled delegation of coding tasks to trusted worker harnesses via MCP, with execution isolation, recovery, and verified handoff.36 npm8Apache 2.0
- AlicenseAqualityBmaintenanceA 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.51MIT
- AlicenseBqualityBmaintenanceEnables 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.2334 npmMIT
- AlicenseAqualityBmaintenanceEnables 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.14MIT