# 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`](https://opencode.ai) 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`](https://opencode.ai) 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`.