open-delegate

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

Goals

Goal	Detail
Reduce Cursor spend	Hand work to cheaper OpenCode alternatives (Zen free, open-weights, mid/cheap OpenRouter)
Real OpenCode handoff	Cursor "delegates" like the native tool, but OpenCode executes
Trivial install	Finds the opencode CLI; env-configurable; one-command local register (npm/Marketplace listing pending)
Guarded model policy	MCP-level default / force catalog / allow / deny; soft always-on routing rule
Guarded lifecycle	Bounded waits, no leaked background processes, real error text
Live preview	Each session returns its own opencode serve URL to open directly

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).

<details> <summary>Pin a default model / policy</summary>

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.

</details>

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

Doc	Topic
skills/ode-delegate/SKILL.md	Agent-facing contract: when/how to use the five tools
skills/ode-delegate/reference/models.md	Cheap force-set pins / job defaults
skills/ode-delegate/reference/tools.md	Tool-by-tool input/output
skills/ode-delegate/reference/config.md	OPEN_DELEGATE_* env vars
skills/ode-delegate/reference/errors.md	Error shapes
rules/open-delegate-routing.mdc	Soft always-on routing (ODE_MODELS / openrouter → ODE)
docs/MODELS_GROUND_TRUTH.md	Cost-first catalog research
CONTRIBUTING.md	Local development, testing, project layout, release gate
RUNBOOK.md	Diagnose host-side connection errors, find logs by pid

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