Extensões

Uma extensão pode oferecer uma página em tela cheia, como um quadro de tarefas. Abra pelo menu Páginas de extensões acima das sessões. O menu só aparece para páginas ativadas e aprovadas. Escolher um chat, recarregar, pausar, remover ou trocar de servidor fecha a página. A extensão não pode abri-la sozinha.

Os dados próprios da extensão ficam no servidor conectado e são apagados ao removê-la. Um quadro pode acompanhar sessões de vários projetos e worktrees sem criar arquivos no seu projeto.

Use Configurações → Extensões para adicionar ao OpenChamber painéis feitos por outras pessoas. Uma extensão é uma página pequena que fica na barra da direita, ao lado dos painéis integrados. Ela pode mostrar dados de outro serviço, anexar uma tarefa ao chat e, se você permitir, iniciar sessões, enviar prompts ou ler arquivos.

As extensões funcionam no OpenChamber web e desktop. O VS Code e o app móvel ainda não as carregam. Elas não são a mesma coisa que plugins do OpenCode.

Instalar uma

Extensões marcadas como Integrada vêm com a instância OpenChamber selecionada. Começam ativadas e recebem as permissões declaradas sem outro diálogo. Use Desativar ou Ativar no cartão. Elas não podem ser removidas nem atualizadas separadamente do app. Desativar preserva os dados e as contas conectadas, e essa escolha permanece após atualizações do app.

As contas ficam em Configurações → Integrações → Integrações nativas. Um serviço ainda pode precisar de um token API ou login para acessar sua conta.

1. Abra Configurações → Extensões.
2. Cole uma destas opções no campo Pasta, ZIP ou URL e escolha Adicionar:
   • o caminho absoluto de uma pasta neste computador
   • o caminho de um arquivo .zip
   • um link https para um repositório git ou um arquivo zip
   • um endereço Git SSH, como [email protected]:owner/extension.git
3. Se a extensão pedir permissões, um diálogo lista todas. Escolha Permitir e ativar, ou Remover para tirá-la de volta.

Você também pode arrastar um .zip para o campo ou escolher um com o botão de arquivo ao lado; o arquivo é enviado ao servidor do OpenChamber, então isso funciona também com uma instância remota. No desktop, o botão de pasta abre um seletor nativo, e uma pasta arrastada é instalada a partir do seu caminho.

O ícone da extensão aparece na barra. Se não aparecer, veja Solução de problemas.

Uma instalação por pasta roda direto daquela pasta, então quem desenvolve uma extensão pode editar e recarregar. Um zip ou uma URL é copiado primeiro para a pasta de dados do OpenChamber; o arquivo original não é tocado.

Repositórios privados e identidades Git

Instalações SSH aceitam [email protected]:owner/extension.git e ssh://[email protected]/owner/extension.git, com #branch-or-tag opcional. Escolha a identidade global ou uma identidade Git salva no menu de impressão digital ao lado do campo. A seleção é mantida para verificar e instalar atualizações; mudanças na chave valem na próxima operação.

A identidade global usa a configuração Git/SSH e o agente SSH do usuário que executa o servidor OpenChamber selecionado. Em uma instância remota, a chave precisa estar disponível naquele servidor. Desbloqueie chaves protegidas por senha no agente SSH do processo do servidor antes de instalar. HTTPS usa as credenciais HTTPS do Git, sem trocar automaticamente para SSH. Os hosts Git devem resolver para endereços públicos; aliases SSH locais e destinos de redes privadas não são aceitos.

O que uma extensão pode fazer

Mostrar um painel e ler qual projeto e sessão estão abertos não precisa de permissão. Tudo que age em seu nome precisa, e você vê a lista inteira uma vez, na instalação:

• Enviar mensagens nas suas sessões: escreve e envia prompts ao modelo, o que gasta tokens e pode executar ferramentas.
• Acessar projetos e sessões: listar projetos, worktrees e estados de sessões, além de criar e abrir sessões em projetos registrados. O conteúdo das conversas permanece privado.
• Ler e gravar arquivos do projeto: qualquer arquivo do projeto aberto.
• Ler e gravar arquivos fora do projeto: só os locais listados no diálogo.
• Usar seu Small Model: geração de texto avulsa fora das suas sessões, com o modelo de Configurações → Sessões → Small Model. Custa tokens.
• Conectar a um serviço externo: com a conta que você conecta em Configurações → Integrações.
• Ler a conversa de uma sessão: só quando você executa a ação da extensão naquela sessão.
• Executar um serviço local: um programa separado com todo o acesso do seu usuário. Permita só se confiar no autor. Quando a extensão quer ser avisada do que acontece nas suas sessões, esta linha também lista os momentos de que ela fica sabendo: um turno termina, um turno falha, o agente pede permissão, o agente faz uma pergunta. Ela fica sabendo deles em todos os projetos, sem nenhuma janela aberta, e recebe só identificadores: a sessão, o projeto dela e os itens que você anexou a ela.
• Ler o que o agente diz em segundo plano: a resposta final de cada turno, as perguntas que o agente faz e o que ele pede permissão para fazer, em todos os projetos, enviados ao serviço local da extensão. Permita só se confiar no destino para onde a extensão envia isso.
• Iniciar sessões e enviar mensagens por conta própria: o serviço local dela faz isso sem nenhuma janela aberta, o que gasta tokens e pode executar ferramentas.
• Adicionar ao que os agentes leem: texto nas instruções das suas sessões, e skills oferecidas a todos os agentes enquanto a extensão estiver ativa.
• Adicionar um plugin ao OpenCode: o plugin do pacote é carregado no seu OpenCode enquanto a extensão estiver ativa. O código do plugin roda dentro do OpenCode com todo o seu acesso, como um serviço local, então permita só se você confia no autor.

Um serviço local também pode continuar rodando enquanto o OpenChamber estiver em execução, ou despertar em um horário. O diálogo diz isso em Executar um serviço local, e diz quando o que você digita depois de @ vai para o serviço. Uma extensão pode adicionar suas próprias linhas ao menu @ e seus próprios blocos às respostas do agente. Pausar a extensão tira tudo isso.

Uma extensão que entrega suas notificações, para o Slack, o Matrix ou um servidor próprio, diz isso também em Executar um serviço local, com uma linha que começa com Entrega suas notificações. Nada sai até você conectar uma conta para ela em Configurações → Integrações; depois disso ela recebe o que o seu celular receberia, e pausar a extensão interrompe isso.

Quando uma versão mais nova pede mais do que você permitiu, o card mostra Precisa de aprovação e um botão Revisar permissões. Até você permitir a nova lista, essa extensão fica desligada.

Onde ela aparece

Além do painel na barra lateral, uma extensão pode adicionar entradas a menus que você já usa: as ações de uma mensagem do chat, o menu de uma sessão, o menu + ao lado da caixa de chat e comandos de barra como /task ABC-12, que anexam algo sem abrir nada. Ela também pode dar às próprias ferramentas um ícone, um título e um layout de saída adequados no chat, como as ferramentas embutidas do OpenChamber têm. A extensão decide quais deles oferece; todos ficam desligados até você permitir a extensão.

Algumas extensões mostram uma imagem ao vivo em vez de um painel próprio: aquilo em que um agente está trabalhando no servidor, como um navegador ou um simulador. Clique na imagem ou digite para assumir o controle; a linha de status mostra Você está no controle e as ações de navegador do agente são recusadas até você pressionar Devolver ao agente. Copiar e colar funcionam normalmente. Outro dispositivo conectado ao mesmo tempo vê quem está no controle e não pode tomá-lo. Uma extensão assim pode adicionar seus próprios controles ao lado da imagem, por exemplo uma barra de endereço acima ou uma coluna de ferramentas ao lado.

Uma extensão com um plugin do OpenCode

Uma extensão pode trazer um plugin do OpenCode, para que você instale uma coisa só em vez de duas. O diálogo de permissões dela tem uma linha que começa com Adicionar um plugin ao OpenCode. Depois que você permite, o OpenChamber adiciona o plugin ao OpenCode que ele roda para você em alguns segundos, sem reinício; desativar ou remover a extensão tira o plugin do mesmo jeito. Nada é escrito no seu próprio opencode.json, então o plugin nunca sobrevive à extensão e nunca roda no OpenCode que você inicia em um terminal.

Quando o OpenChamber não iniciou o OpenCode com o qual conversa, ou o seu ambiente define o próprio OPENCODE_CONFIG, a configuração do OpenChamber não chega a esse OpenCode. A tela da extensão diz isso e oferece Adicionar à configuração global. Isso escreve a pasta do plugin na sua configuração global do OpenCode: ele passa a rodar em todo OpenCode deste computador, inclusive no terminal, continua ativo enquanto a extensão estiver desativada, e é seu para gerenciar em Configurações → Plugins. Se você remover a extensão, o OpenCode mostra essa entrada como um plugin com falha e continua funcionando até você apagar a entrada lá. Um OpenCode em outra máquina não consegue carregar uma pasta desta; a tela diz isso.

O VS Code e o app móvel não carregam extensões. Uma sessão dentro de um espaço isolado roda o próprio OpenCode, que nunca recebe o plugin. No modo empresarial o plugin conta como um serviço local: a extensão só instala a partir de um repositório listado pelo seu administrador.

Uma extensão como host Git

Uma extensão pode adicionar um host Git ao lado do GitHub, GitLab, Gitea, Forgejo e Gerrit. A caixa de permissões dela passa a ter uma linha que começa com Atua como o host Git e dá o nome do host. A linha também diz o que o OpenChamber envia a ela: nomes de repositórios, branches e o texto de issues e pull requests que você escreve.

Depois que você permite, o host ganha seu próprio card em Configurações → Integrações, ao lado dos hosts integrados. Conecte sua conta ali com um token, e com o endereço do host se o card pedir. A partir daí, um projeto cujo remoto está nesse host funciona como qualquer outro: as issues e pull requests dele aparecem no quadro Issues e PRs e no menu + do chat, os branches dele mostram selos de pull request e você pode começar um worktree a partir de um dos pull requests dele. Veja Hosts Git para o que cada uma dessas coisas faz.

Seu token fica no OpenChamber. A extensão pede ao OpenChamber que chame o host por ela, e o OpenChamber adiciona o token a cada chamada, só para o endereço que você conectou. A extensão nunca o recebe.

Pausar a extensão tira o host até você ligá-la de novo, e sua conta continua. Remover a extensão esquece a conta. O VS Code não mostra hosts Git de extensões.

O SDK do OpenChamber tem um exemplo funcional, examples/source-control-provider, para começar ao construir um. Veja Construir uma extensão.

Uma extensão como rastreador

Uma extensão pode adicionar um rastreador de itens de trabalho ao lado do Linear: YouTrack, Jira, Plane ou um rastreador próprio. A caixa de permissões dela passa a ter uma linha que começa com Atua como o rastreador e dá o nome dele. A linha também diz o que o OpenChamber envia a ele: suas buscas e os itens que você abre, e que ele é solicitado a mudar o estado deles e publicar comentários de sessão por você.

Depois que você permite, o rastreador ganha seu próprio card em Configurações → Integrações sob Contas de extensões. Conecte uma conta ali: com um token, ou entrando pelo navegador depois de informar o client id do app que você registrou no rastreador, e antes o endereço do servidor se o card pedir. A partir daí, os itens dele estão onde os do Linear estão: o menu + do chat e o seletor, New Worktree, os itens vinculados de uma sessão e os estados ao vivo dos itens que você acompanha. Um link colado para um dos itens dele é reconhecido do mesmo jeito. Veja Linear para o que cada uma dessas coisas faz.

Seus tokens ficam no OpenChamber. A extensão pede ao OpenChamber que chame o rastreador por ela, e o OpenChamber adiciona a credencial a cada chamada, só para o servidor que você conectou. A extensão nunca a recebe, e só as chamadas dela de mudança de estado e de comentário podem escrever algo lá.

Pausar a extensão tira o rastreador até você ligá-la de novo, e suas contas continuam. Remover a extensão as esquece. O VS Code não mostra rastreadores; no celular os itens do rastreador aparecem, e as contas são conectadas pelo app web ou desktop.

O SDK do OpenChamber tem um exemplo funcional, examples/tracker-provider, com um rastreador falso para rodar ao lado. Veja Construir uma extensão.

Uma extensão como provedor de uso

Uma extensão pode adicionar um provedor de uso ao lado dos integrados: um provedor que o OpenChamber não lê sozinho, ou um dela mesma. Seu diálogo de permissões passa a ter uma linha que começa com Informa o uso como um provedor integrado e lista os provedores do OpenCode cujas credenciais ela lê, como openrouter; uma extensão que não lista nenhum diz isso.

Depois que você a permite, o cartão dela fica depois dos provedores integrados em Configurações → Uso, com o nome e o ícone da extensão, e entra nos limites do cabeçalho, no status de trabalho, no popover do celular e na bandeja do desktop quando você marca Mostrar no status de trabalho, como qualquer provedor integrado. A cada atualização o OpenChamber entrega à extensão a credencial que o OpenCode guarda para cada provedor listado, e nada mais; uma versão que lista outro provedor pede sua aprovação de novo. A extensão lê o uso por conta própria, e o OpenChamber o desenha como desenha o de um provedor integrado.

Pausar a extensão tira o cartão até você ligá-la de novo, e suas configurações de uso para ela continuam. Remover a extensão tira o cartão de vez. O VS Code não mostra uso de extensões; no celular o cartão aparece, e a extensão é configurada no aplicativo web ou desktop. Uma sessão dentro de um espaço isolado lê o uso do servidor próprio desse espaço, que não tem extensões.

O SDK do OpenChamber tem um exemplo funcional, examples/quota-provider, com uma API de uso falsa para rodar ao lado. Veja Construir uma extensão.

Conectar a conta dela

Uma extensão que fala com um serviço ganha um card em Configurações → Integrações sob Contas de extensões. Dependendo do serviço, o card pede um token de API, um usuário e token, ou um client id para um fluxo de login. Escolha Conectar; Desconectar esquece o token guardado. Campos extras que a extensão declara são salvos sozinhos quando você sai deles.

O token fica no servidor do OpenChamber. A página da extensão nunca o vê.

Atualizar

Extensões instaladas a partir de uma URL git podem se atualizar sozinhas. Abrir Configurações → Extensões verifica cada uma no máximo uma vez por hora; Verificar atualizações verifica na hora. Um card com versão mais nova mostra Atualização disponível e um botão Atualizar. A atualização mantém suas permissões, contas e configurações; se a nova versão pedir mais, o diálogo de aprovação aparece de novo. Instalações por pasta ou zip não se atualizam: substitua-as à mão.

Adicione #v1.2.0 ou #stable à URL git ao instalar para seguir uma tag ou branch em vez do branch padrão.

Pausar ou remover

Cada card tem uma chave Ativado. Desligada, mantém a extensão instalada, mas esconde o painel e bloqueia as chamadas. Remover apaga uma instalação por zip ou URL da pasta de dados do OpenChamber; numa instalação por pasta só esquece o caminho, sua pasta continua lá.

Criar a sua

Tudo que uma extensão pode fazer, e como criar uma, está em Criar uma extensão.