Nexus para OpenCode

Nexus é um plugin para o OpenCode que coordena uma execução sequencial com três papéis independentes:

Usuário → Planner → Executor → Reviewer → Executor (se necessário) → validação global

O Planner continua no loop após cada tarefa: ele recebe o resultado, decide continuar, replanejar ou encerrar. O Executor trabalha em uma tarefa por vez. O Reviewer aprova ou devolve instruções de correção estruturadas.

Estado atual

Implementado e validado no OpenCode CLI 1.18.18:

• Plugin legado V1, usando a API pública @opencode-ai/plugin instalada nessa versão.
• Plugin TUI (@opencode-ai/plugin/tui), que registra o comando /nexus com um assistente visual de seleção de modelos.
• Modelos independentes para Planner, Executor e Reviewer (Reviewer usa o modelo do Planner quando não configurado).
• Effort (variant low/medium/high) configurável por papel, no config ou por chamada.
• Sessões-filhas com parentID, prompts por modelo/agente e interrupção por sessão.
• Estado JSON local, retries, replanejamentos, limite global de iterações e cancelamento.
• Contratos JSON validados em runtime e um reparo controlado quando a resposta é inválida.
• Testes unitários e execuções CLI reais: fluxo com /nexus (assistente TUI), fluxo legado e nexus_models.

Consulte a investigação de compatibilidade para evidências e limitações.

Instalação

O Nexus é instalado como um pacote npm global e registrado nas configurações do OpenCode por um instalador cross-platform (Linux, macOS e Windows). O OpenCode já deve estar instalado.

Instalar via npm (todas as plataformas)

O pacote está publicado no npm. Instale com o comando padrão:

npm install -g nexus-opencode
nexus-opencode install

Instalar do tarball (gera o pacote local)

cd nexus-opencode            # raiz do repositório
npm install
npm run build
npm pack                     # gera nexus-opencode-0.1.0.tgz
npm install -g ./nexus-opencode-0.1.0.tgz
nexus-opencode install

Instalar da pasta do repositório

npm install -g /caminho/para/o/repositorio
nexus-opencode install

O instalador adiciona o plugin do servidor em opencode.json(c) e o plugin TUI em tui.json(c) da configuração global do OpenCode (~/.config/opencode/), e copia commands/nexus.md para o diretório global de comandos. Depois, reinicie o OpenCode e use /nexus.

Instalar a partir do repositório (desenvolvimento)

npm install
npm run build
npm run install:global        # registra no config global
# ou
nexus-opencode install --project   # registra apenas no projeto atual

Instalar direto do git

npm install -g <url-do-repositorio>
nexus-opencode install

O script prepare do pacote compila o dist/ automaticamente na instalação via git.

Publicar no npm

O pacote está publicado como nexus-opencode. Para publicar novas versões:

npm version patch        # ou minor/major
npm publish --access public

Desinstalar

nexus-opencode uninstall
# ou
nexus-opencode uninstall --project

Comandos do instalador

nexus-opencode install              registra no config global (padrão)
nexus-opencode install --project    registra apenas no projeto atual
nexus-opencode uninstall            remove os registros
nexus-opencode status               mostra o que está registrado

O instalador é idempotente e preserva o conteúdo existente (incluindo comentários em opencode.jsonc/tui.jsonc e outras entradas de plugin, como opencode-quota).

Pré-requisitos por plataforma

O Nexus roda sobre o OpenCode e o Node.js (>= 20):

| Plataforma | Node.js | OpenCode | | --- | --- | --- | | Linux Arch | sudo pacman -S nodejs npm | curl -fsSL https://opencode.ai/install \| bash ou AUR (opencode) | | Linux Fedora | sudo dnf install nodejs npm | curl -fsSL https://opencode.ai/install \| bash | | Linux Debian/Ubuntu | sudo apt install nodejs npm | curl -fsSL https://opencode.ai/install \| bash | | macOS | brew install node | curl -fsSL https://opencode.ai/install \| bash ou brew install opencode | | Windows | nodejs.org ou winget install OpenJS.NodeJS.LTS | winget install opencode ou opencode.ai |

Depois dos pré-requisitos, os comandos de instalação do Nexus são os mesmos em todas as plataformas:

npm install -g <tarball-ou-repositorio>
nexus-opencode install

Este repositório inclui .opencode/plugins/nexus.js, um entrypoint de desenvolvimento descoberto automaticamente pelo OpenCode quando ele é iniciado na raiz deste projeto, e o plugin TUI compilado em dist/tui.js, registrado via .opencode/tui.json.

Para instalar o pacote em outro projeto, adicione-o como dependência e registre o entrypoint compilado no opencode.json(c) do projeto:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    [
      "./node_modules/nexus-opencode/dist/index.js",
      {
        "models": {
          "planner": "provider-a/model-x",
          "executor": "provider-b/model-y",
          "reviewer": "provider-a/model-z"
        },
        "agents": {
          "planner": "plan",
          "executor": "build",
          "reviewer": "plan"
        },
        "reviewerEnabled": true,
        "stateDirectory": ".opencode/nexus/runs",
        "efforts": {
          "planner": "high",
          "executor": "low"
        },
        "limits": {
          "maxTaskRetries": 3,
          "maxPlannerReplans": 3,
          "maxGlobalIterations": 50,
          "maxResponseRepairs": 3,
          "maxSessionRetries": 2
        }
      }
    ]
  ]
}

Os modelos não são acoplados a providers específicos. O Nexus verifica, pela API do OpenCode, se cada provider/model informado existe e está conectado antes de iniciar a run. Se um modelo não for configurado, o papel usa o modelo padrão que o OpenCode resolver para a sessão.

Esforço de raciocínio (effort)

Cada papel pode receber um effort (low, medium ou high) via efforts na configuração ou por chamada com planner_effort/executor_effort. O Nexus traduz o effort para a variant do modelo no prompt (variant: "low" | "medium" | "high"), o mecanismo nativo do OpenCode que mapeia para reasoningEffort/thinking do provider.

• Modelos com variants built-in (OpenAI o-series/gpt-5, Anthropic, Google, etc.) aplicam o effort imediatamente.
• Para outros modelos, defina variants equivalentes na configuração do OpenCode, por exemplo:

{
  "provider": {
    "openai": {
      "models": {
        "gpt-5": {
          "variants": {
            "low": { "reasoningEffort": "low", "textVerbosity": "low" },
            "medium": { "reasoningEffort": "medium", "textVerbosity": "low" },
            "high": { "reasoningEffort": "high", "textVerbosity": "low" }
          }
        }
      }
    }
  }
}

• O Reviewer usa efforts.reviewer (padrão: não definido, sem variant).
• Sem effort configurado, o Nexus não envia variant e o modelo usa o padrão da sessão.

Recuperação de erros do provider

Se o provider falhar durante um prompt (ex.: erro de raciocínio do DeepSeek ao reutilizar histórico de tool-calls, rate limit), o Nexus abre uma nova sessão para o papel e reenvia o prompt, até maxSessionRetries vezes (padrão: 2). A nova sessão zera o histórico do provider, contornando erros que dependem de estado acumulado. Erros de autenticação não são retentados.

Como usar

Assistente visual (/nexus)

Na interface TUI, o plugin registra o comando /nexus com um assistente que usa apenas os providers/modelos já conectados no OpenCode:

1. Digite /nexus e selecione o comando sugerido.
2. Escolha o modelo Principal (Planner).
3. Escolha o modelo Trabalhador (Executor).
4. Escolha o effort do Principal e do Trabalhador (low, medium, high ou manter o padrão).
5. Descreva a tarefa e confirme.

O assistente injeta o pedido com os modelos escolhidos (e reviewer_model igual ao modelo do Principal) e o agente inicia a run via nexus_run. O esc cancela o assistente a qualquer momento.

O registro TUI é feito por um arquivo tui.json:

{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": ["./node_modules/nexus-opencode/dist/tui.js"]
}

Sem a interface TUI, o agente usa o mesmo fluxo de escolha por ferramentas (veja abaixo).

Ferramentas

O plugin expõe quatro ferramentas ao agente principal:

• nexus_run: inicia uma run.
• nexus_status: mostra o estado persistido de uma run.
• nexus_cancel: cancela uma run e interrompe sessões-filhas ativas quando possível.
• nexus_models: lista os providers/modelos conectados, para seleção visual quando o assistente TUI não estiver disponível.

Peça ao OpenCode para usar nexus_run, por exemplo:

Use nexus_run para implementar autenticação por token. Planeje, execute, revise e valide.

Também é possível passar os modelos e efforts por chamada:

Use nexus_run com planner_model=provider-a/model-x,
executor_model=provider-b/model-y e reviewer_model=provider-c/model-z.

Use nexus_run com planner_effort=high e executor_effort=low.

Há um comando opcional em commands/nexus.md. Copie-o para .opencode/commands/nexus.md e use:

/nexus implemente autenticação por token

Se o pedido começar com escolher (ou pedir explicitamente para escolher modelos), o comando usa nexus_models e a ferramenta question para o usuário escolher o modelo Principal e o Trabalhador — o mesmo fluxo do assistente TUI, mas por ferramentas. Em qualquer outro caso, chama nexus_run diretamente com o pedido.

O reviewer_model é opcional: quando não informado, o Nexus usa o modelo do Planner. O planner_effort/executor_effort são opcionais e aceitam low, medium ou high.

Fluxo e garantias

nexus_run
  ├─ Planner (sessão filha, sem edit/bash/task)
  ├─ Executor por tarefa (sessão filha, modelo próprio)
  ├─ Reviewer por tentativa (sessão filha, sem edit/bash/task)
  ├─ Planner decide continue/replan/complete/fail
  └─ Executor em modo de validação global (sem edição)

• O Planner recebe o pedido original, plano e resultados resumidos; não recebe a implementação inteira a cada etapa.
• O Executor recebe somente a tarefa atual, critérios de aceite e um resumo curto das tarefas já concluídas.
• O Reviewer recebe a tarefa, critérios, relatório do Executor e resumo dos diffs; ele também pode ler o projeto.
• Uma reprovação retorna ao mesmo Executor com instruções concretas. maxTaskRetries é o número de correções permitido além da primeira execução.
• Um erro persistente obriga o Planner a replanejar; ultrapassar o limite encerra a run com erro explícito.
• O estado é gravado de forma atômica em .opencode/nexus/runs/<run-id>.json. Como ele contém o pedido original e logs operacionais, mantenha-o fora do versionamento se isso for sensível.

Segurança

O Nexus não altera permissões globais nem implementa bypasses.

• Planner e Reviewer recebem permissões de sessão que negam edit, bash e task.
• Executor mantém as permissões normais do agente configurado, mas não recebe as ferramentas nexus_*, evitando recursão.
• A validação global permite shell do Executor, mas nega edição e subagentes.
• O diretório de estado precisa ser relativo e permanecer dentro do diretório de projeto da sessão.
• Nenhum comando destrutivo é executado pelo Nexus por conta própria.

Desenvolvimento e validação

npm run typecheck
npm test

O teste real executado nesta implementação usou o CLI do OpenCode 1.18.18 e o fluxo completo:

Planner → Executor cria nexus-integration.txt → Reviewer aprova → validação global → completed

O Desktop não foi exercitado em uma execução de interface ponta a ponta; veja a classificação em docs/INVESTIGATION.md.