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.

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.