IA no terminal: a proposta de integrar o opencode ao Hyper

Artigo elaborado por IA(claude), objetivo: divulgar a issue.

A issue #31, aberta no repositório hyper, propõe algo específico e bem delimitado: trazer um agente de IA de linha de comando, o opencode, para dentro da experiência do terminal Hyper. Não se trata de embutir um modelo de IA no próprio terminal, mas de integrar uma ferramenta externa já existente e madura ao fluxo de trabalho do usuário.

O que é o Hyper

O Hyper é um terminal construído sobre tecnologias web — Electron e React — em vez das bibliotecas nativas usadas pela maioria dos emuladores de terminal tradicionais. Essa escolha de arquitetura tem uma consequência direta: interfaces, temas e funcionalidades podem ser escritos com HTML, CSS e JavaScript, e estendidos através de um sistema de plugins já consolidado, configurado pelo arquivo ~/.hyper.js. Isso torna o Hyper um terreno particularmente fértil para experimentação — plugins podem alterar cores, adicionar atalhos, injetar painéis inteiros na interface, ou interceptar a entrada e saída do shell.

É justamente essa flexibilidade que a issue #31 tenta explorar: em vez de reescrever o núcleo do terminal, usar a camada de plugins existente para acoplar um agente de IA à experiência do usuário.

O que é o opencode

O opencode é um agente de IA de código aberto, construído especificamente para viver no terminal — funcionando tanto como CLI quanto como uma interface TUI (interface textual interativa) completa, com opções adicionais de desktop e integração a IDEs. Diferente de um simples chat, o opencode tem acesso direto a um conjunto de ferramentas que pode invocar autonomamente durante uma sessão: leitura, escrita e edição de arquivos; execução de comandos no shell configurado; busca de conteúdo e padrões em arquivos; e navegação de código via integração com LSP (Language Server Protocol) para localizar definições, referências e símbolos.

Na prática, isso significa que é possível pedir ao opencode para implementar uma funcionalidade, e ele vai ler os arquivos relevantes, aplicar as mudanças e até rodar uma verificação de build — sem que o desenvolvedor precise copiar e colar código manualmente entre janelas.

Alguns detalhes técnicos do opencode são especialmente relevantes para o tipo de integração proposta na issue:

• Modo não interativo: o opencode pode ser executado com um prompt passado diretamente como argumento (opencode -p "..."), retornando a resposta em texto puro ou em JSON (-f json) — o que facilita chamadas programáticas vindas de outra aplicação, como um plugin do Hyper.
• Servidor headless: o comando opencode serve sobe um servidor HTTP com uma especificação OpenAPI exposta em /doc, permitindo que outras aplicações se comuniquem com o agente via API em vez de apenas via linha de comando.
• SDK oficial em JS/TS: existe um SDK oficial (@opencode-ai/sdk) que facilita a integração de aplicações JavaScript — relevante justamente porque o Hyper é construído em Electron/React.
• Suporte a múltiplos provedores de IA: o opencode é "bring-your-own-provider", ou seja, não está preso a um único modelo ou empresa — o usuário conecta a chave de API do provedor de sua escolha.
• Modos Plan/Build: o agente pode operar em um modo de planejamento (analisando e propondo mudanças sem aplicá-las) ou de execução direta, o que tem implicações diretas para como um painel de IA dentro do Hyper poderia expor essas duas etapas ao usuário.
• Inicialização de projeto: rodar o comando de inicialização faz o opencode ler a estrutura do projeto e gerar um arquivo AGENTS.md, documentando padrões de código e organização — um contexto que a integração poderia aproveitar para o painel de sessões.

O escopo desenhado na issue

A issue organiza o trabalho em cinco frentes concretas, todas ainda como itens de checklist em aberto:

1. Plugin de integração: um plugin do Hyper que detecte automaticamente se o opencode está instalado no sistema e, a partir disso, ofereça atalhos e comandos integrados — o ponto de entrada de toda a proposta.
2. Painel/sidebar de IA: uma interface lateral dentro do próprio terminal, exibindo as sessões de conversa com o opencode, com histórico de interações e um campo de prompt — trazendo a conversa com o agente para o mesmo espaço onde o código é escrito e executado.
3. Comandos rápidos personalizáveis: atalhos de teclado configuráveis para invocar o opencode em modos específicos, como explicar um erro que acabou de aparecer no terminal, refatorar um trecho selecionado ou gerar testes para um arquivo.
4. Renderização de saída do agente: melhorias na exibição de markdown e blocos de código gerados pela IA dentro da interface do Hyper, já que respostas de agentes costumam vir formatadas com essa estrutura.
5. Configuração via ~/.hyper.js: seguindo o padrão de configuração já usado pelo terminal, permitindo definir ali o provedor de IA, o modelo e a chave de API a serem usados pela integração.

Fora do escopo, por ora

A issue delimita explicitamente duas frentes que ficam de fora nesta primeira fase: suporte nativo a múltiplos provedores de IA além do opencode, e a implementação de um modelo de IA embutido no próprio Hyper. Ou seja, o objetivo inicial não é transformar o Hyper em uma plataforma de IA agnóstica de agente, mas validar profundamente uma única integração antes de generalizar.

O ponto técnico em aberto

A consideração mais interessante levantada na issue é sobre como essa comunicação entre Hyper e opencode deveria acontecer. O opencode já expõe CLIs que podem ser invocadas programaticamente — o que cobre bem o caso de comandos rápidos e chamadas pontuais. Mas a issue levanta a possibilidade de avaliar uma API ou CLI adicional no próprio opencode para permitir comunicação assíncrona entre as duas ferramentas.

Essa distinção importa na prática: invocar o opencode em modo de prompt único e esperar uma resposta funciona bem para comandos pontuais, mas um painel de sessões com histórico contínuo — como o descrito no item 2 do escopo — se beneficia mais de uma conexão persistente, no estilo do que o servidor headless do opencode já oferece via HTTP e OpenAPI. É essa ponte entre o modelo de execução por comando e um modelo de sessão contínua que a issue deixa como questão em aberto para quem for implementar.

A issue está aberta para discussão e contribuições, com o foco inicial mantido exclusivamente no opencode.