Plugins

Um plugin reúne skills e servidores MCP, e às vezes comandos, agents ou hooks, para você adicionar uma capacidade completa de uma só vez. Desde a 0.20.0, o Maestrly instala os plugins por conta própria e entrega as skills e as ferramentas MCP deles a todos os modelos, seja qual for o provedor da conversa. Você não precisa de uma versão do plugin para cada modelo.

O Maestrly lê três formatos de plugin: Agent Plugins (plugin.json), Codex (.codex-plugin/plugin.json) e Claude Code (.claude-plugin/plugin.json).

Abrir a central de plugins

Abra Configurações → Maestrly Chat → Plugins. O composer também leva até lá: Explorar plugins fica no fim do menu + e do menu de skills. Numa conversa de um host de workspaces remotos, o link abre os plugins desse host.

Os plugins pertencem a um host. Use o seletor Configurações de para escolher Este computador ou um ambiente de workspaces de um servidor; cada um tem os próprios plugins. A central tem duas visões: Explorar e Instalados. Em Explorar, busque plugins e filtre por Categoria e Fonte.

Fontes

Uma fonte é um repositório Git público que lista plugins, como faz um marketplace do Codex ou do Claude Code, ou um repositório que é um único plugin. O Maestrly sugere duas fontes, openai/plugins e openai/community-plugins. Os plugins delas são listados quando você abre a fonte.

Para adicionar uma fonte:

Em Fontes, escolha Adicionar fonte.
Informe o Repositório como uma URL https:// ou dono/repo. Se quiser, informe também uma branch, tag ou commit e as pastas a baixar, uma por linha.
Escolha Adicionar fonte.

Adicionar uma fonte só lista os plugins dela. Nada é instalado nem executado até você instalar um plugin e aprovar o que ele precisa. As fontes exigem o Git no host, e só repositórios públicos funcionam; um que peça login é recusado.

O Maestrly não revisa plugins de fontes de terceiros. Toda fonte além das duas sugeridas é marcada como Terceiros, e os detalhes dos plugins dela também. Instale só plugins de publishers em quem você confia.

Atualizar busca a fonte de novo, e os plugins instalados com versão mais nova mostram Atualização disponível. Remover deixa de listar os plugins de uma fonte. Se há plugins dela instalados, você pode desinstalá-los junto ou manter a fonte.

Compatibilidade

O Maestrly oferece só o que funciona igual com todos os modelos, então trocar de modelo nunca muda o que um plugin faz. Cada plugin está em um de dois estados:

Estado	Significado
Funciona em todos os modelos	As skills e os servidores MCP dele, e as partes que o Maestrly adapta, funcionam igual seja qual for o provedor da conversa.
Não compatível	Nada nele funciona igual com todos os modelos. Ele não é oferecido e não pode ser instalado.

A lista mostra só os plugins que funcionam em todos os modelos. Abaixo dela, um contador como 3 plugins não funcionam igual com todos os modelos abre os plugins deixados de fora, cada um com o motivo. Um plugin não é compatível quando:

depende de conectores de apps do ChatGPT e não traz um servidor MCP para o mesmo serviço, então as skills dele esperariam ferramentas que só existem dentro dos produtos da OpenAI;
não tem nenhuma skill nem servidor MCP que o Maestrly consiga rodar;
o manifesto é inválido, ou a fonte ou o marketplace o excluem.

O Maestrly adapta o que consegue. Os comandos de um plugin viram skills que você inicia com /<plugin>:<comando>, os agents viram subagents e o Maestrly roda os hooks por conta própria. Partes que só funcionam dentro de um produto, como conectores de apps, servidores de linguagem e hooks de eventos que o Maestrly não controla, nunca são ativadas para nenhum modelo. Elas aparecem nos detalhes do plugin em Não incluído, cada uma com o motivo; nada é descartado em silêncio.

Um plugin instalado que deixa de ser compatível, por exemplo depois que os arquivos dele mudam, deixa de valer em todas as conversas. Ele continua em Instalados com o motivo, e você pode atualizá-lo ou desinstalá-lo.

Instalar um plugin

Abra um plugin para ver os componentes, a compatibilidade, a licença, as capacidades declaradas, os endpoints externos que os servidores MCP acessam, os scripts e executáveis, os requisitos e as configurações que ele pede. Um plugin é código do publisher dele, então confira antes a licença e os termos do publisher.

Escolha Instalar. Antes de instalar qualquer coisa, o Maestrly pede que você:

aprove cada servidor MCP que roda como processo local (stdio);
reconheça que o plugin traz scripts ou executáveis que os agentes podem rodar, com a sua aprovação, pela ferramenta de shell;
aprove os hooks do plugin, se ele tiver. Cada hook aparece com o evento e o comando. Você pode instalar o plugin sem eles e ligá-los depois;
escolha onde o plugin vale: Todas as conversas ou Projetos selecionados do host;
preencha as configurações que o plugin pede. Valores secretos ficam mascarados, são guardados criptografados no host e nunca são mostrados de novo.

Se a fonte mudou depois que você abriu o plugin, o Maestrly mostra a versão nova para você revisar antes de instalar.

Usar um plugin

As skills de um plugin se chamam <plugin>:<skill>. Elas aparecem no menu de skills do composer e em Configurações → Maestrly Chat → Skills, sob o nome do plugin. Você pode ligá-las e desligá-las, colocá-las em grupos de skills e substituí-las numa conversa, como as suas próprias skills. Elas só são removidas junto com o plugin. Veja Maestro, agentes e skills.

Agents

Os agents de um plugin viram subagents chamados <plugin>-<agent>. Qualquer modelo pode delegar a eles com task ou com uma menção #<plugin>-<agent>, como faz com os seus próprios agents. Os detalhes do plugin os listam.

Ferramentas: as ferramentas que um agent cita são mapeadas para as do Maestrly. Read, Grep, Glob, LS, Bash, Edit, MultiEdit, Write, WebFetch e WebSearch mantêm o significado, e qualquer ferramenta mcp__… vira acesso aos servidores MCP ativados. WebSearch só funciona com a busca na web ligada nas Configurações. Ferramentas sem equivalente que todos os modelos possam usar, como Task ou TodoWrite, ficam de fora e aparecem em Não incluído. Um agent que não cita ferramentas recebe o conjunto somente leitura.
Modelo: o model de um agent é ignorado. Ele roda no modelo da conversa, a menos que uma regra em Configurações → Maestrly Chat → Modelos & agentes → Perfis de execução dos subagents escolha outro.
Nomes: um arquivo de agent do projeto (.claude/agents, .agents/agents) ou da sua pasta pessoal com o mesmo nome vence o do plugin.

Hooks

Os hooks de um plugin são comandos que o publisher escreveu para rodar em momentos definidos de uma conversa. O Maestrly os roda por conta própria, com o formato de entrada e saída do Claude Code, então eles se comportam igual com todos os modelos. Estes são os eventos suportados; outros eventos, e hooks que não são comandos, aparecem em Não incluído.

Evento	Quando	O que o hook pode fazer
`SessionStart`	No primeiro turno de uma conversa, no primeiro turno num host em que os hooks ainda não tinham rodado (uma conversa movida, por exemplo) e no primeiro depois de limpá-la ou compactá-la	Adicionar contexto para o modelo
`UserPromptSubmit`	Em cada mensagem que você envia, antes de ela ser guardada	Adicionar contexto ou bloquear a mensagem
`PreToolUse`	Antes de cada chamada de ferramenta	Bloquear a chamada ou mudar a entrada dela
`PostToolUse`, `PostToolUseFailure`	Depois de uma chamada de ferramenta dar certo ou falhar	Adicionar um texto que o modelo lê junto com o resultado
`Stop`	Quando o agente termina um turno	Manter o agente trabalhando, com um motivo, no máximo 8 vezes seguidas

Aprovação: os hooks só rodam depois que você os aprova, na instalação ou depois, com a chave Hooks em Instalados. Uma atualização que os altera pede de novo.
Onde: os hooks rodam só em conversas dos modos Agente e Design, no host que roda a conversa, na pasta dela. Eles nunca rodam em conversas dos modos Pergunta, Plano ou Maestro.
Permissões: um hook pode negar uma chamada de ferramenta ou bloquear uma mensagem, mas a resposta allow ou ask dele nunca dispensa o pedido de permissão do próprio Maestrly.
Todos os modelos: numa conversa com hooks de ferramenta, os modelos Codex usam as ferramentas de shell, arquivos e busca na web do Maestrly no lugar das deles, então toda chamada passa pelos hooks. As chamadas de ferramenta dos subagents também os executam.
Mensagens: a mensagem, a falha ou o timeout de um hook aparece acima do composer e não é guardado na conversa. Quando um hook bloqueia a sua mensagem, ela volta para o composer. Mensagens de um bot, do app para celular ou do agente de outra conversa passam pelos mesmos hooks.
Limite de tempo: um hook tem 60 segundos, a menos que defina outro timeout, de até 10 minutos. Parar o encerra.
Companion do ChatGPT: ele não consegue executar hooks SessionStart, UserPromptSubmit ou Stop, então não inicia numa conversa Agente com um plugin que os tenha. Desligue os hooks desse plugin ou limite onde ele vale.

Servidores MCP

Os servidores MCP de um plugin aparecem no menu + e em Configurações → Maestrly Chat → Ferramentas, marcados como De <plugin>. Desligue um servidor numa conversa pelo menu +. Desligue-o em todo lugar, ou ligue-o de novo, em Plugins.

Um servidor que usa OAuth mostra Precisa entrar. Escolha Entrar ao lado dele, em Instalados ou em Ferramentas, e termine no navegador. O login fica guardado no host que roda o servidor, que o renova quando preciso. Servidores que usam um token pedem esse token como configuração.

Várias contas

Um servidor OAuth pode ter várias contas conectadas, por exemplo um e-mail pessoal e um de trabalho. Escolha Adicionar conta sob o servidor e selecione a outra conta no seletor de contas do provedor. Cada conta recebe o nome do e-mail, quando o provedor o informa, ou um nome numerado, como Account 1 e Account 2; escolha Renomear para mudar o nome. Em cada conta você pode:

escolher Alterar para definir onde ela vale: todas as conversas ou projetos selecionados;
escolher Entrar de novo quando ela mostrar Precisa entrar, por exemplo depois que o login expirou;
escolher Remover para desconectá-la.

Quando uma conversa pode usar várias contas de um servidor, o modelo diz o nome da conta em cada chamada e pergunta a você quando não está claro de qual você fala. Você pode desligar uma conta numa conversa pelo menu +. Com uma única conta, nada muda.

Cliente OAuth próprio

Alguns servidores, como os do Google, não registram apps automaticamente. Entrar num deles mostra um formulário para Seu próprio cliente OAuth: crie um cliente no provedor do servidor, do tipo app desktop ou nativo, com redirecionamento loopback, e informe o Client ID e, se houver, o Client secret. O secret fica criptografado no host que roda o servidor e nunca é mostrado de novo. Cliente OAuth próprio, sob o servidor, permite alterar ou remover o cliente.

Com o Google:

No Google Cloud Console, abra APIs e serviços → Credenciais → Criar ID do cliente OAuth e escolha App para computador.
Ative a API do serviço no mesmo projeto, por exemplo a Gmail MCP API.
Na tela de consentimento OAuth, adicione suas contas como usuários de teste. Com o app no modo Testing, o Google encerra cada login após 7 dias, então você entra de novo toda semana.

Gerenciar os plugins instalados

Instalados lista os plugins do host. Em cada plugin você pode:

ligá-lo ou desligá-lo, e ligar ou desligar cada servidor MCP e os hooks dele. Ligar os hooks os mostra para a sua aprovação;
escolher Alterar para definir onde ele vale;
escolher Atualizar quando a fonte tem uma versão mais nova. Se a versão nova muda o que roda, como um servidor local novo, scripts novos ou hooks alterados, o Maestrly pede a sua aprovação de novo;
escolher Editar configurações;
escolher Desinstalar. As skills e as ferramentas MCP dele saem de todas as conversas, e as configurações salvas são apagadas. Marque Apagar também os dados do plugin para remover os arquivos que os servidores dele guardam.

Um plugin marcado como Precisa de configuração ou Servidor precisa de aprovação está sem uma configuração obrigatória ou sem a aprovação de um servidor local. Os servidores MCP dele que dependem disso ficam desligados até você fornecê-los; as skills continuam funcionando.

Workspaces remotos e ambientes de bots

Workspaces remotos

Com um ambiente de workspaces escolhido em Configurações de, a central de plugins gerencia os plugins desse ambiente. Eles são baixados e rodam no servidor, nesse ambiente, e as conversas dele os usam. Projetos selecionados lista os workspaces do ambiente. Nada é copiado entre este computador e o servidor, nem entre ambientes.

Quando uma conversa muda para outro computador ou ambiente, ela usa os plugins instalados lá. O que você desligou nela, como o servidor de um plugin ou uma conta, continua desligado onde o mesmo plugin está instalado. Os logins são os do destino.

Ambientes de bots

Abra as configurações do ambiente (Configurações do ambiente, a engrenagem na visão do ambiente) e escolha Plugins. A central de plugins funciona da mesma forma, com estas diferenças:

O ambiente baixa, confere e roda os plugins por conta própria, e eles atendem todas as conversas dele.
Trazer deste computador instala no ambiente um dos plugins deste computador. O ambiente o baixa da mesma fonte, no mesmo commit, confere com as aprovações que você deu neste computador e guarda, criptografadas, as configurações que você informou aqui. Os arquivos do plugin nunca são copiados deste computador. Se o ambiente não conseguir conferir a sua aprovação, instale o plugin pelas fontes do ambiente e revise-o lá.
Entrar num servidor do ambiente abre a página de consentimento no navegador deste computador. O ambiente guarda o login, e as contas dele atendem todas as conversas.
As skills dos plugins aparecem nas configurações de Skills do ambiente, sob o nome de cada plugin.

Atualize antes o servidor de bots e o ambiente. Até lá, a aba pede que você atualize um ou o outro. Veja Bots e servidor de bots.

Segurança

Um plugin é código do publisher dele. O Maestrly mostra a licença, os endpoints, os comandos locais e os scripts antes de você instalar, mas não revisa plugins de fontes de terceiros.
Uma skill é um conjunto de instruções, então uma maliciosa pode conduzir o agente. As ações dele ainda passam pelos pedidos de permissão do Maestrly, que não perguntam no modo Acesso total.
Cada servidor MCP local precisa da sua aprovação do comando exato de inicialização, e os scripts e os hooks também. Uma atualização que muda o que roda pede de novo.
Os hooks rodam comandos no host, com as suas permissões, sem perguntar a cada vez. Eles podem impedir uma ação, mas não podem aprová-la por você.
Os valores que você informa para um plugin são guardados criptografados no host e nunca são mostrados de novo. Sem armazenamento seguro no host, eles são recusados.
Os plugins só são baixados de repositórios Git públicos via HTTPS. Links simbólicos e submódulos não são instalados.
Os servidores locais de um plugin rodam no host que o instalou: este computador, um host de workspaces remotos ou um ambiente de bots.

Para ver todos os detalhes, leia o guia técnico (em inglês).

A seguir: Projetos e Git.