opencode-bridge-for-claude-code

Let Claude Code hand its easy and medium work to cheaper opencode agents, keep the hard work for itself, and see exactly what every opencode session is doing.

A single-file, zero-dependency MCP server (Node 18+), with an equivalent Rust implementation (7 ms start, 6 MB memory; see rust/). It gives Claude Code ten tools:

• Delegate a task to an opencode agent (explorer, librarian, fixer, oracle, ...) with the delegation policy enforced by the tool, not left to a prompt that gets forgotten.

• Watch every opencode session on the machine (the ones you started, the ones your subagents started, the TUI ones): which are running, which failed, what each one said and did.

• Name sessions consistently (LANE/agent: task) so a list of forty sessions is readable.

Companion repository: opencode-config. The agent roster this bridge delegates to (explorer, librarian, deep-research, oracle, fixer, designer) and the opencode-side routing rules live there. Install it as ~/.config/opencode first. Without it only the bridge's built-in worker agent exists and most of what makes the delegation useful is missing.

Why

Delegating to a cheaper model saves tokens only if it is done with discipline: send the right kind of work, never the work where a silent mistake corrupts a result, verify what comes back, and know what is running. In practice three things go wrong:

1. The routing mode is forgotten. A project can be "sensitive" (quality-critical: delegate only recon, docs, literature and checks) or "insensitive" (aggressive offload) or the default "blueprint" mode. Instructions in a CLAUDE.md get missed after a context reset. Here the mode is detected and enforced in the tool call, and it is also sent to Claude as MCP server instructions.

2. Nobody can see the opencode sessions. Subagents start opencode run jobs that nobody tracks. The bridge reads the opencode service's own session store.

3. Sessions are called "Entropy-based selection of RNA structures", "New session - 2026-..." and so on. A fixed LANE/agent: task title makes them sortable and searchable.

Related MCP server: opencode-delegate

Quick start

Requirements: Node.js >= 18, opencode v2 with its background service (tested with 2.2.7; the bridge uses the opencode api command and the /api/session routes), the opencode-config agents, and a C compiler only if you want to run the process tests.

# 1. the opencode side: agent roster and routing rules. The roster is on the v2 branch (the default branch is older)
git clone -b v2 https://github.com/Subhajit-Roy-Partho/opencode-config ~/.config/opencode     # back up an existing ~/.config/opencode first

# 2. the bridge
git clone https://github.com/Subhajit-Roy-Partho/opencode-bridge-for-claude-code ~/.claude/mcp/opencode-bridge

claude mcp add --scope user opencode-bridge \
  -e OPENCODE_BRIDGE_ROOT="$HOME/projects" \
  -e OPENCODE_BRIDGE_MODEL='provider/model#variant' \
  -- node ~/.claude/mcp/opencode-bridge/server.mjs

claude mcp get opencode-bridge      # Status: ✔ Connected

OPENCODE_BRIDGE_ROOT is the only directory tree delegated tasks may work in. Restart Claude Code once; the tools appear as mcp__opencode-bridge__opencode_*. If you use several Claude config directories (CLAUDE_CONFIG_DIR), run the claude mcp add line once per directory with CLAUDE_CONFIG_DIR=... claude mcp add ....

Prefer the Rust binary? Build it with rust/build.sh (Docker) or cargo build --release and register that binary instead of node .../server.mjs; same tools, same environment variables, same tests (rust/README.md).

Then add a short section to your CLAUDE.md so Claude prefers the bridge: see examples/claude-md-snippet.md.

The tools

Example (illustrative; opencode_sessions state=running):

2 session(s) (state=running); scanned 100; service-active ids: 0
ses_e3188e02...  running  deep-research  <1m ago  650k/29k tok  Github/project-a  ALPHA/deep-research: collect API reference notes
ses_e31688286... running  worker         <1m ago    0/0 tok     Github/project-a  BETA/worker: rename api_key to apiKey in the loader

Example (illustrative; opencode_session_output mode=tail):

ses_e31688286...  succeeded  worker  updated <1m ago  19k/78 tok
Github/project-a  |  BETA/worker: rename api_key to apiKey in the loader
----------------------------------------
[00:09:57] agent -> worker
[00:10:02] user: Rules: do the work yourself, ... READ-ONLY / build-and-test line ... <the task>
[00:10:04] assistant: Renaming in three files.
  -> edit({"path":"src/loader.js", ...}) [completed] => ok
[00:10:36] assistant: DONE
[00:10:37] - idle (succeeded) -

States: running (no outcome yet, and recent or reported active by the service), succeeded, failed, interrupted, and stale? (no outcome but quiet for 45 minutes: crashed, killed, or a very long silent tool call). Runs started with --standalone (as the bridge does) are not in the service's own active list, so for them running comes from recency.

The delegation policy (modes and tiers)

The policy is the one in docs/POLICY.md; in short:

Tiers. Only easy and medium work is delegated: literature search, quote extraction, DOI lookups, bulk download / parse / convert / clean, table collation, boilerplate and glue scripts, functions with a given spec, unit tests, README drafts, plots from given tables, mechanical refactors, UI against a written blueprint. Hard and moderately hard work stays on Claude: experiment and protocol design, split and leakage decisions, anything touching held-out data, model and feature design, statistics and every reported number, scoring / metric / energy code, non-obvious debugging, architecture, interpretation. If a silent mistake would change a result, do not delegate; if unsure, treat the job as one tier harder. opencode_start refuses tier: "hard" and "unsure".

Modes.

Sensitive always wins when sources disagree. The project root is the nearest parent of the working directory that has a .claude or .git. Call opencode_policy (optionally with cwd) to see the result and the reason.

Also enforced. Prompts that look like they contain a secret (API keys, tokens, private keys, password=...) are refused before anything starts. Read-only agents get an explicit read-only instruction, editing agents a "run the build/test and fix until it passes" instruction, and every run is told never to commit or push. The output is always an untrusted draft: Claude is told to check files exist, rerun tests, recompute numbers, inspect git diff.

Session naming

<LANE>/<agent>: <task>: LANE in capitals (a lane or repository short name), agent = the opencode agent, task = 3-8 words. Example: DOCS/librarian: collect API notes. opencode_start sets it from lane (default: upper-cased directory name) and the first line of the prompt, or from an explicit title. For a plain opencode run pass --title; an explicit title is kept (opencode's automatic title generator backs off from custom titles). opencode_session_rename fixes old ones; opencode_sessions title_prefix="DOCS/" lists one lane. Details: docs/SESSION-NAMING.md.

Limits, errors and recovery

The bridge assumes things go wrong and says what to do about it (docs/ERRORS.md has the full tables):

• Provider errors (rate limit, quota, context length, output limit, overload, auth, bad model or agent, network) are parsed from opencode's error events and stderr, classified, and returned with advice. Only transient errors of read-only agents that produced no output are retried automatically (backoff 20 s, 60 s); an agent that edits files is never replayed.

• Runaway work: at most 6 tasks at once, a 120 minute timeout per task, and cancel / timeout / disconnect kill the whole process group, including the shell commands the agent started.

• Size limits: prompts over ~100 KB are attached as a file (Linux limits one argument to 128 KiB); replies are capped at 100000 characters; output is kept up to 2 MB per task.

• Service problems: a stopped, hung or unauthorised opencode service, or a huge reply, produces a one-line message, not a stack trace; long scans stop at a deadline and say PARTIAL.

Configuration

How it works

All session reads go through opencode api GET /api/session..., which talks to the opencode background service and handles its authentication, so the bridge never touches credentials. Routes used: session.list, session.get, session.message.list, session.active, session.update (title only). Delegated runs are opencode run --standalone --agent <agent> --title <title> --auto --format json, in cwd inside the allowed root. Nothing is ever deleted or interrupted by the bridge, and opencode_cancel only kills processes it started itself. Notes on the API: docs/API-NOTES.md.

Tests

npm test                 # 190 offline tests: fake opencode, no network, no tokens
npm run test:live        # 7 live tests against your real opencode service (spends a few thousand tokens, cleans up after itself)
BRIDGE_BIN=/path/to/opencode-bridge npm test    # the same suite against the Rust binary

The offline suite covers the MCP protocol, every tool and every parameter, pagination across pages, state / stale detection, output rendering and truncation, rename, the process table (against a compiled stand-in binary named opencode), mode detection from every source and their precedence, tier and agent enforcement per mode, the secret guard, and every error path: provider errors and their classification, the retry rules, timeouts and process-group kills, the parallel limit, oversized prompts, service failures, shutdown. See docs/TESTING.md.

Limitations

• opencode v2 only (/api/... routes). The older opencode serve HTTP API with /session is not supported.

• The bridge runs one opencode run --standalone process per task; it does not keep a long-lived opencode server of its own. Task state is in memory: after a restart of the bridge the opencode sessions remain readable, but the tasks are no longer listed.

• tier and mode are enforced mechanically, but whether a task is really "easy" is still Claude's judgement. The policy cannot read the task.

• Session output can contain whatever the agent saw, including file contents. The tools are read-only but the text goes to the model.

Prior art

Other MCP servers for opencode exist, for example nosolosoft/opencode-mcp and several listed on Glama. They mostly wrap the older HTTP API with basic auth. This one targets the v2 service through opencode api, adds the policy enforcement and the naming convention, and is designed for the opencode-config agent roster.

License

MIT