open-delegate

Delegate a Cursor task to a real, unattended background OpenCode agent — cheaper model, isolated history — through five small MCP tools.

Goals

Non-goals

• Supporting IDEs other than Cursor

• Chasing Anthropic/OpenAI flagship quality (Opus / Sonnet / Fable / GPT Sol / Terra are out of curated defaults)

• Cursor slug → OpenCode remapping

• Task-kind / persona auto-routing beyond configurable force / allow / deny lists

• Replacing the native delegate tool for Cursor-native models not on the force list

Prerequisites

1. Cursor (this plugin is Cursor-only).

2. Node.js ≥ 18.17 (nodejs.org or your package manager).

3. OpenCode CLI on your PATH (or set OPEN_DELEGATE_OPENCODE_BIN to its full path).

Install OpenCode

Pick one (package name on npm is opencode-ai, not opencode):

macOS / Linux

# Recommended one-liner
curl -fsSL https://opencode.ai/install | bash

# Or via npm
npm i -g opencode-ai@latest

# Or Homebrew (tap stays more up to date than the official formula)
brew install anomalyco/tap/opencode

Windows

npm i -g opencode-ai@latest

# Or Scoop / Chocolatey
scoop install opencode
# choco install opencode

Verify:

opencode --version

Configure a model

OpenCode needs at least one usable model. Either:

• Run opencode auth login (or /connect inside the OpenCode TUI) and add a provider API key, or

• Use a free hosted model such as opencode/deepseek-v4-flash-free (no API key required for that path).

Docs: opencode.ai/docs.

Install

Note: @verbalize/open-delegate is not yet published on npm, and the Cursor Marketplace listing is pending. Until then, install from a git clone (below), which registers a local Cursor plugin pointed at your build.

git clone git@github.com:Verbalize-public/open-delegate.git
cd open-delegate
npm install
npm run build
npm run register:local

Then Cursor → Developer: Reload Window. Customize → MCP Tools should list open-delegate with five tools: ode_delegate, ode_await, ode_transcript, ode_cancel, ode_diagnostics.

register:local syncs the plugin into ~/.cursor/plugins/local/open-delegate with an mcp.json that runs node <checkout>/dist/index.cjs (avoids the npx 404 while the package is unpublished), and registers a workspaceOpen hook so Cursor loads that path. Re-run after moving the repo, pulling changes, or editing src/ (rebuild first).

Edit the installed ~/.cursor/plugins/local/open-delegate/mcp.json (keep the absolute args path the sync wrote):

{
  "mcpServers": {
    "open-delegate": {
      "command": "node",
      "args": ["/absolute/path/to/open-delegate/dist/index.cjs"],
      "env": {
        "OPEN_DELEGATE_DEFAULT_MODEL": "opencode/deepseek-v4-flash-free"
      }
    }
  }
}

On Windows the args path looks like C:/Users/<you>/…/open-delegate/dist/index.cjs (forward slashes are fine).

Optional lists (CSV): OPEN_DELEGATE_ODE_MODELS, OPEN_DELEGATE_ALLOW_MODELS, OPEN_DELEGATE_DENY_MODELS. For a large custom force list, prefer OPEN_DELEGATE_ODE_MODELS_FILE (JSON array or CSV path) over a giant env CSV.

For a full OpenCode config blob (advanced), use OPEN_DELEGATE_OPENCODE_CONFIG_CONTENT instead.

Full env reference: skills/ode-delegate/reference/config.md.

How it works

Cursor (MCP client)
   │  stdio, JSON-RPC
   ▼
open-delegate MCP server  (this repo → dist/index.cjs)
   │  spawns + owns
   ▼
opencode serve  (1 shared default runtime)
   │  HTTP via OpenCode's client SDK
   ▼
model / provider

• Soft rule rules/open-delegate-routing.mdc: if the named model is on ODE_MODELS or is openrouter/…, use ode_delegate + ode_await (not native Task).

• The default opencode serve runtime is pre-warmed right after MCP connect, so most ode_delegate calls hit an already-warm process.

• ode_delegate returns a stable sessionId within a few seconds — status: "running" if setup already finished, or status: "starting" if it's still finishing in the background; poll with ode_await (timeoutMs: 0 for a single peek). Optional waitMs can finish short tasks in one call. Pass sessionId to resume a finished session.

• Before starting a prompt, models are checked against the live OpenCode provider.list() snapshot (fail-fast MODEL_NOT_AVAILABLE).

• Prompts are capped at ~512KiB inline; use promptPath for anything larger.

• ode_await polls OpenCode's /session/status + message list — never the MCP server's own say-so alone.

• If opencode serve crashes, every session pinned to it is marked "error" immediately (no hang).

• Closing the MCP connection disposes every spawned opencode serve process.

• Internal events are logged as one-line JSON to stderr and to a PID-named file; ode_diagnostics reads them back live — see config.md and errors.md.

Documentation

Contributing

Issues and PRs welcome. See CONTRIBUTING.md for local setup, tests, project layout, and the maintainer release gate.

Troubleshooting

Hit a "Connection stopped"/timeout in Cursor, or need to find an opencode process's log by pid? See RUNBOOK.md.

License

MIT