Skip to main content
Glama
Sign In
opencode-bridge

opencode-bridge

by Guipegoraro
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

opencode-bridge

An MCP server that lets Claude Code delegate coding tasks to external models running on a local opencode serve, so the main agent's tokens go to planning and review instead of mechanical implementation work.

Claude Code  --MCP stdio-->  opencode-bridge  --HTTP/SSE-->  opencode serve  -->  delegated model

Platform

This project is Windows-first. The MCP server itself (src/index.ts, a Node.js stdio process) is portable to any OS Node runs on. What is not portable is the supervision layer: the serve is kept alive by the Windows Task Scheduler, and the setup/maintenance scripts (scripts/*.ps1) are PowerShell 7. Everything under SETUP.md, TROUBLESHOOTING.md and docs/USO-NO-CLAUDE-CODE.md was written and measured on Windows.

Running this on Linux or macOS would require rewriting the supervision layer — a systemd unit or a launchd agent in place of the scheduled task, and a shell equivalent of scripts/install-serve-task.ps1, scripts/start-serve.ps1 and scripts/sync-opencode-config.ps1. None of that exists in this repository today; this section states what the gap is, not that it is filled.

Related MCP server: opencode MCP server

Requirements

  • Node.js 20+ and npm.

  • opencode installed and on PATH, already authenticated with at least one provider.

  • PowerShell 7.3+ (pwsh) — used by the setup and maintenance scripts.

  • Claude Code, to register the bridge as an MCP server.

Installation

  1. Clone the repository (the scheduled-task script assumes %USERPROFILE%\opencode-bridge by default — see SETUP.md §2 if you clone elsewhere).

  2. npm install && npm run build.

  3. pwsh -File .\scripts\install-serve-task.ps1 — generates the serve credential and registers the scheduled task that starts opencode serve at user logon.

  4. pwsh -File .\scripts\sync-opencode-config.ps1 — mirrors the MCPs configured in Claude Code into opencode's config and restarts the serve.

  5. Copy bridge.config.example.json to bridge.config.json and point aliases/cheapModel at models your own opencode provider actually exposes (check with opencode models, or with list_models once step 6 is done). Without this file, delegate_task still works by passing a raw "provider/model", but bridge_health deep: true has no cheapModel to probe with and fails. sync-overrides.json follows the same copy-the-example pattern, if you need to change which MCPs the sync step excludes or adds.

  6. Register opencode-bridge as an MCP server in Claude Code (exact JSON in docs/USO-NO-CLAUDE-CODE.md §1) and run the bridge_health tool with deep: true until it comes back green.

Full walkthrough, including the serve's authentication model and what to adjust if you did not clone into the default path: SETUP.md.

Tools

Tool

What it does

delegate_task

Creates a session and delegates a task to an external model, waiting for the result.

continue_task

Sends a follow-up prompt to an existing session, with full history.

task_progress

Inspects a running session (tool-call count, todo list) without interrupting it.

abort_task

Stops the round in progress; keeps the session for inspection or resume.

end_task

Ends and deletes a session on the server.

list_tasks

Lists sessions known to the server, recovering ones the bridge's registry lost.

list_models

Lists every model the opencode server offers, plus your configured aliases.

bridge_health

Checks the whole delegation chain: credential, serve, auth, models, skills, and optionally a real MCP call.

Detailed parameters, when to use each tool and when not to: docs/USO-NO-CLAUDE-CODE.md.

Documentation

  • SETUP.md — installation, the serve's authentication model, changing the delegated agent's MCP list.

  • docs/USO-NO-CLAUDE-CODE.md — how to register the bridge in Claude Code, the tool catalog, environment variables, model selection.

  • TROUBLESHOOTING.md — symptom → cause → the command that fixes it.

  • docs/APRENDIZADOS.md — what building this taught about signals, gates and silent failure modes; useful even if you never run this bridge.

License

MIT — see LICENSE.

opencode-bridge (português)

Um servidor MCP que permite ao Claude Code delegar tarefas de código a modelos externos rodando num opencode serve local, para que os tokens do agente principal sejam gastos em planejamento e revisão, não em trabalho mecânico de implementação.

Claude Code  --MCP stdio-->  opencode-bridge  --HTTP/SSE-->  opencode serve  -->  modelo delegado

Plataforma

Este projeto é Windows-first. O servidor MCP em si (src/index.ts, um processo stdio em Node.js) é portável para qualquer SO que rode Node. O que não é portável é a camada de supervisão: o serve é mantido de pé pelo Agendador de Tarefas do Windows, e os scripts de instalação/manutenção (scripts/*.ps1) são PowerShell 7. Tudo em SETUP.md, TROUBLESHOOTING.md e docs/USO-NO-CLAUDE-CODE.md foi escrito e medido no Windows.

Rodar isto em Linux ou macOS exigiria reescrever a camada de supervisão — uma unit systemd ou um agente launchd no lugar da tarefa agendada, e um equivalente em shell de scripts/install-serve-task.ps1, scripts/start-serve.ps1 e scripts/sync-opencode-config.ps1. Nada disso existe neste repositório hoje; esta seção diz qual é a lacuna, não que ela está preenchida.

Requisitos

  • Node.js 20+ e npm.

  • opencode instalado e no PATH, já autenticado em pelo menos um provider.

  • PowerShell 7.3+ (pwsh) — usado pelos scripts de instalação e manutenção.

  • Claude Code, para registrar a ponte como servidor MCP.

Instalação

  1. Clone o repositório (o script da tarefa agendada assume por padrão %USERPROFILE%\opencode-bridge — veja SETUP.md §2 se você clonar em outro lugar).

  2. npm install && npm run build.

  3. pwsh -File .\scripts\install-serve-task.ps1 — gera a credencial do serve e registra a tarefa agendada que sobe o opencode serve no logon do usuário.

  4. pwsh -File .\scripts\sync-opencode-config.ps1 — espelha os MCPs configurados no Claude Code na config do opencode e reinicia o serve.

  5. Copie bridge.config.example.json para bridge.config.json e aponte aliases/cheapModel para modelos que o seu provider do opencode realmente oferece (confira com opencode models, ou com list_models depois do passo 6). Sem esse arquivo, delegate_task continua funcionando passando "provider/model" direto, mas bridge_health deep: true fica sem cheapModel para testar e falha. sync-overrides.json segue o mesmo padrão de copiar o exemplo, se você precisar mudar quais MCPs o passo de sync exclui ou acrescenta.

  6. Registre opencode-bridge como servidor MCP no Claude Code (JSON exato em docs/USO-NO-CLAUDE-CODE.md §1) e rode a tool bridge_health com deep: true até ela voltar verde.

Passo a passo completo, incluindo o modelo de autenticação do serve e o que ajustar se você não clonou no caminho padrão: SETUP.md.

Tools

Tool

O que faz

delegate_task

Cria uma sessão e delega uma task a um modelo externo, esperando o resultado.

continue_task

Manda um follow-up numa sessão existente, com o histórico inteiro.

task_progress

Inspeciona uma sessão em andamento (contagem de tool calls, todo list) sem interromper.

abort_task

Para a rodada em andamento; mantém a sessão para inspeção ou retomada.

end_task

Encerra e apaga uma sessão no servidor.

list_tasks

Lista sessões conhecidas pelo servidor, recuperando as que o registro da ponte perdeu.

list_models

Lista todo modelo que o servidor opencode oferece, mais os apelidos configurados.

bridge_health

Verifica a cadeia inteira de delegação: credencial, serve, auth, modelos, skills e, opcionalmente, uma chamada real de MCP.

Parâmetros detalhados, quando usar cada tool e quando não usar: docs/USO-NO-CLAUDE-CODE.md.

Documentação

  • SETUP.md — instalação, modelo de autenticação do serve, troca da lista de MCPs do agente delegado.

  • docs/USO-NO-CLAUDE-CODE.md — como registrar a ponte no Claude Code, catálogo de tools, variáveis de ambiente, escolha de modelo.

  • TROUBLESHOOTING.md — sintoma → causa → o comando que resolve.

  • docs/APRENDIZADOS.md — o que construir isto ensinou sobre sinais, gates e formas silenciosas de falha; útil mesmo que você nunca rode esta ponte.

Licença

MIT — veja LICENSE.

Available Tools

8 tools
abort_taskA

Abort the round running in a delegation session. The session and its history are KEPT for inspection or resume, and the bridge will never re-prompt an aborted session. Use it when two spaced task_progress checks show no growth AND the worktree is unchanged. Not the same as end_task, which deletes the session.

Inputs: session_id (required).

bridge_healthA

Check the whole delegation chain in one call: credential file readable, serve up and STABLE (two spaced reads, so a dying instance cannot pass), auth enforced, provider models present, skills valid. With deep=true also runs a REAL MCP call through a disposable delegation on the cheapest model, then deletes that session. Run it with deep=true before a batch of delegations and whenever the environment smells broken - it is the manual liveness test turned into code. Do not run deep=true in a loop: it spends tokens.

Inputs: deep, model.

continue_taskA

Send a follow-up message to an existing delegation session (full history preserved). Same monitoring guarantees as delegate_task: hard wait ceiling, and a session that ends in error comes back as an error.

USE IT FOR: iterating on work that came back good, or asking for the final summary when the answer came back empty. DO NOT use it while a round is still running - it queues a second prompt on top of the one in flight; check task_progress first. DO NOT use it to switch models: a session belongs to the model it was created with, so relaunch with delegate_task instead.

Inputs: prompt (required), session_id (required), model, effort.

delegate_taskA

Delegate a coding task to an external model running in OpenCode. The delegated model runs an agentic loop with the MCP servers configured in opencode and the skills from ~/.claude/skills - it is a full worker, not a single completion call.

Monitoring is event-driven (SSE) with poll fallback and a hard ceiling (OPENCODE_MAX_POLL_MS, default 45 min) - it never waits forever. Empty responses are retried automatically; a session that ends in error comes back as an error, not as an empty success; if the opencode server is down the bridge restarts it. Run bridge_health first when in doubt.

USE IT FOR: an atomic task whose design is already decided in the prompt. AVOID IT FOR: open design decisions (the model will fill the gap with something plausible) and long build/run loops inside the agent.

TRAP: use ABSOLUTE paths for every file in the prompt, even when passing 'directory'. If the wait hits the ceiling you get an error carrying the session_id - the model MAY STILL BE RUNNING on the server: check task_progress before continue_task.

CHOOSING THE MODEL - MANDATORY: if the user did not name a model for this task, DO NOT pick one on your own. Call list_models, then propose ONE model with a one-line reason ("qwen3.7-plus: multi-file refactor, needs the bigger context") and ask the user to confirm or change it. Once they answer, reuse that choice for the following delegations in this conversation until they say otherwise. Only skip the question when the user already named the model.

RETURNS: session_id for continue_task / task_progress / abort_task / end_task.

Inputs: model (required), prompt (required), title, effort, +1 more.

end_taskA

End and DELETE a delegation session on the server, clearing this bridge's registry for it. Use it once the work is accepted. There is no recovery afterwards: to stop the work but keep the history, use abort_task instead.

Inputs: session_id (required).

list_modelsA

List what this opencode server actually offers: every provider/model, its effort levels (opencode calls them "variants"), context window and whether it reasons - plus the aliases configured in bridge.config.json.

USE IT BEFORE delegate_task whenever the user has not named a model: pick a candidate here, then propose it to them with a one-line reason. It is also how you find the valid 'effort' values, which differ per model.

The catalog is large (hundreds of models across providers), so the output is capped. It always reports how many models matched and how many were left out - if something you expect is missing, narrow with 'query'/'provider' or raise 'limit' instead of assuming it is not there.

Inputs: limit, query, provider, reasoning_only.

list_tasksA

List delegation sessions from the SERVER (survives bridge restarts), enriched with this bridge's registry. Use it to recover a session_id when a delegate_task failed without returning one.

IMPORTANT: GET /session on the opencode server is SCOPED BY DIRECTORY. This tool sweeps the server's default scope plus every directory this bridge knows about, and it always prints which scopes it swept. If the bridge was restarted its registry is empty, so a session created with a project directory may not show up - in that case call it again passing that directory explicitly.

Inputs: directory.

task_progressA

Inspect a running delegation without interrupting it: tool-call count (the reliable liveness signal), last tools, todo list. HOW TO READ IT: a tool-call count that grows between two spaced checks means it is working; a todo list that stops moving does NOT mean it is stuck, and is not a reason to abort - the model does not update it while working. For ground truth on files, run 'git status --short' in the worktree. This answers 'alive vs stalled', never 'how much is left'.

Inputs: session_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A4.7/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool has a clearly distinct lifecycle role: delegate starts, continue follows up, task_progress inspects, abort pauses, end deletes, list_tasks recovers, list_models selects, bridge_health validates. No two tools could be confused for the same action.

    Naming Consistency4/5

    Most tools follow verb_noun (delegate_task, continue_task, abort_task, end_task, list_tasks, list_models), but task_progress and bridge_health break the verb-first pattern. The names remain readable and predictable, so the inconsistency is minor.

    Tool Count5/5

    Eight tools is well-scoped for a delegation bridge: the full session lifecycle (create, resume, monitor, abort, delete, list) plus model discovery and health checking. Every tool serves a necessary purpose with no redundancy.

    Completeness5/5

    The tool surface covers the complete delegation workflow: starting, continuing, inspecting, aborting, ending, listing, model selection, and health verification. There are no obvious missing operations for the stated purpose of managing external coding task delegations.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers