You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit c988e16
Browse filesBrowse the repository at this point in the historyBrowse files
feat(mcp): delegate through background opencode-worker agents by default
The delegate tool blocks the main thread until OpenCode finishes. The server
instructions now define delegating as spawning opencode-worker subagents in the
background, and the worker sets background: true so it never runs in the
foreground.
Copy file name to clipboardExpand all lines: README.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -43,7 +43,7 @@ The run uses your existing OpenCode auth, config, agents and permission rules.
43
43
44
44
## Automatic routing
45
45
46
-
The MCP server sends `instructions` that clients inject into every session's system prompt, even when the tools themselves are deferred. They make delegation the default for self-contained implementation (new code, multi-file edits, tests, refactors, boilerplate) and broad read-only exploration, while Claude keeps planning, one-line edits, git and delivery, and anything the user asked it to do itself. The text lives in `INSTRUCTIONS` in `src/index.ts`.
46
+
The MCP server sends `instructions` that clients inject into every session's system prompt, even when the tools are deferred; they make delegation the default for self-contained implementation and broad read-only exploration, and define delegating as spawning `opencode-worker` subagents in the background (one per independent task, parallel when files do not overlap) so the main thread is never blocked; the `delegate` tool blocks until OpenCode finishes, so it is used only on request or when no Agent tool is available; Claude keeps planning, one-line edits, git and delivery, and anything the user asked it to do itself; the text lives in `INSTRUCTIONS` in `src/index.ts`.
47
47
48
48
A plugin PreToolUse hook (`scripts/route-to-opencode.sh`, wired by `plugin-hooks/hooks.json`) rewrites `Agent`/`Task` calls to Claude Code's built-in subagents into a call to `opencode-delegate:opencode-worker` on Haiku. The `description` and any other input keys are kept; the worker runs the task through `opencode run` using OpenCode's configured default model. The prompt is kept as is for `general-purpose` and untyped calls. `Explore`, `Plan` and `claude-code-guide` calls get a `Read-only task (routed from the ... subagent).` prefix, which forces the worker into read-only mode. `statusline-setup` gets a `Routed from the ... subagent.` note; `claude` is kept as is. Only these built-ins are routed: custom, project, user and plugin agents (reviewers and SDD agents included, and `opencode-worker` itself) are never routed and stay on Claude.
Copy file name to clipboardExpand all lines: agents/opencode-worker.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,6 +3,7 @@ name: opencode-worker
3
3
description: Forwards one scoped task to a model running in OpenCode (Grok, Kimi, GLM, Qwen, DeepSeek, …) through `opencode run` and reports what happened. Use proactively for self-contained implementation work (new code, multi-file edits, tests, refactors, boilerplate) and broad read-only exploration, when the user or caller asks for an OpenCode model, when fanning a task out to several OpenCode models in parallel from a workflow, or when a cheap or fast outside model should do grunt work under Claude's supervision. Also receives Claude Code's built-in subagent calls, which the plugin's PreToolUse hook routes here automatically. Put the model name (e.g. "grok 4.7", "kimi k3"), if any, and the task in the prompt.
4
4
tools: Bash
5
5
model: haiku
6
+
background: true
6
7
---
7
8
8
9
You are a thin forwarder. You run one `opencode run` command, then report. You do not gather context, review the result, fix anything or retry. The caller (Claude) reviews; iteration means the caller invokes you again with the session id and feedback.
Copy file name to clipboardExpand all lines: dist/index.js
+5-5Lines changed: 5 additions & 5 deletions
Original file line number
Diff line number
Diff line change
@@ -21974,12 +21974,12 @@ async function waitTask(task, waitSec) {
21974
21974
21975
21975
// src/index.ts
21976
21976
var pkg = JSON.parse(readFileSync(join2(import.meta.dir, "..", "package.json"), "utf8"));
21977
-
var INSTRUCTIONS = `Delegate implementation to OpenCode by default; you stay the orchestrator.
21978
-
- Send every self-contained code change (new code, multi-file edits, tests, refactors, boilerplate) to \`delegate\`, or \`delegate_async\` for long or parallel runs. Send broad read-only exploration there too, with \`auto: false\`.
21977
+
var INSTRUCTIONS = `Delegate implementation to OpenCode by default; you stay the orchestrator. Delegating means spawning background agents, never blocking the main thread.
21978
+
- Launch the \`opencode-delegate:opencode-worker\` subagent (Agent tool, in the background; set \`run_in_background: true\` where the Agent tool offers it) for every self-contained code change (new code, multi-file edits, tests, refactors, boilerplate) and for broad read-only exploration (say "read-only" in its prompt). Spawn one worker per independent task, in parallel when they do not edit the same files, and keep working while they run.
21979
+
- Do not call the \`delegate\` tool for this: it blocks the main thread until OpenCode finishes. Use \`delegate\` or \`delegate_async\` only when the user asks for the MCP tools or no Agent tool is available; if they are deferred, load them (search "opencode delegate") first.
21979
21980
- Keep for yourself: planning and design decisions, one-line edits, git/commit/PR/delivery, and anything the user asked you to do yourself.
21980
-
- The OpenCode model cannot see this conversation: write a self-contained brief (goal, files, constraints, acceptance checks). Omit \`model\` unless the user named one.
21981
-
- After it returns, review the reported git changes and run the project's checks before reporting. For fixes, continue with its \`session_id\` instead of redoing the work yourself.
21982
-
- If these tools are deferred, load them (search "opencode delegate") before the first call.`;
21981
+
- The OpenCode model cannot see this conversation: give the worker a self-contained brief (goal, files, constraints, acceptance checks). Name a model only if the user named one.
21982
+
- When a worker reports back, review its git changes and run the project's checks before reporting. For fixes, spawn the worker again with its session id and precise feedback instead of redoing the work yourself.`;
21983
21983
var server = new McpServer({ name: "opencode-delegate", version: pkg.version }, { instructions: INSTRUCTIONS });
// Injected into every session's system prompt (unlike tool descriptions, which deferred-tool clients
18
18
// hide until loaded), so this is what makes Claude delegate implementation without being asked.
19
-
constINSTRUCTIONS=`Delegate implementation to OpenCode by default; you stay the orchestrator.
20
-
- Send every self-contained code change (new code, multi-file edits, tests, refactors, boilerplate) to \`delegate\`, or \`delegate_async\` for long or parallel runs. Send broad read-only exploration there too, with \`auto: false\`.
19
+
constINSTRUCTIONS=`Delegate implementation to OpenCode by default; you stay the orchestrator. Delegating means spawning background agents, never blocking the main thread.
20
+
- Launch the \`opencode-delegate:opencode-worker\` subagent (Agent tool, in the background; set \`run_in_background: true\` where the Agent tool offers it) for every self-contained code change (new code, multi-file edits, tests, refactors, boilerplate) and for broad read-only exploration (say "read-only" in its prompt). Spawn one worker per independent task, in parallel when they do not edit the same files, and keep working while they run.
21
+
- Do not call the \`delegate\` tool for this: it blocks the main thread until OpenCode finishes. Use \`delegate\` or \`delegate_async\` only when the user asks for the MCP tools or no Agent tool is available; if they are deferred, load them (search "opencode delegate") first.
21
22
- Keep for yourself: planning and design decisions, one-line edits, git/commit/PR/delivery, and anything the user asked you to do yourself.
22
-
- The OpenCode model cannot see this conversation: write a self-contained brief (goal, files, constraints, acceptance checks). Omit \`model\` unless the user named one.
23
-
- After it returns, review the reported git changes and run the project's checks before reporting. For fixes, continue with its \`session_id\` instead of redoing the work yourself.
24
-
- If these tools are deferred, load them (search "opencode delegate") before the first call.`;
23
+
- The OpenCode model cannot see this conversation: give the worker a self-contained brief (goal, files, constraints, acceptance checks). Name a model only if the user named one.
24
+
- When a worker reports back, review its git changes and run the project's checks before reporting. For fixes, spawn the worker again with its session id and precise feedback instead of redoing the work yourself.`;
0 commit comments