Plugins

Adicione agentes, skills, ferramentas e automações em um único plugin.

Gerencie plugins na TUI

Digite /extensions e pressione m para abrir o navegador unificado de Plugins.

• Esquerda e direita navegam entre Todos, Instalados, cada marketplace, Workspace e Adicionar marketplace.
• Cima e baixo navegam na coleção selecionada. / pesquisa nela e Enter abre detalhes roláveis.
• Os detalhes mostram identidade exata do inventário, Extension Profile atual, revisão, agentes, skills, servidores MCP, hooks, serviços, comandos executáveis e observações da origem antes da mutação.
• Pressione Enter novamente numa listagem disponível para instalar e ativar. Use g para uma URL Git direta, u para revisar e atualizar um plugin global instalado ou d para desinstalá-lo.
• Pressione e em um plugin instalado para configurar sua participação pelo campo de mensagem de Extension Profile.

Abertura. Comece em /extensions e escolha Plugins and Marketplace.

Revisão do pacote. Uma única tela mostra a contagem completa de contribuições antes da ativação.

Revisão de capacidades executáveis. Role a mesma tela para inspecionar comandos MCP e de hooks incluídos no plugin.

Uma instalação Git direta pergunta se o checkout pertence a .agents/plugins (convenção compartilhada de Agent Plugins) ou .clarvis/plugins (inventário nativo do Clarvis). Listagens do marketplace são instaladas no inventário compartilhado .agents/plugins. Nos dois casos, instalar é o consentimento explícito para o plugin completo e adiciona a instalação exata ao Extension Profile atual. Não há uma segunda tela de aprovação de plugin ou de hooks.

Plugins instalados globalmente não precisam de uma segunda aprovação do workspace. Já os plugins do repositório precisam de aprovação do seu conteúdo.

Ao iniciar, o Clarvis verifica todos os plugins instalados no workspace, mesmo os que o perfil atual não selecionou. Uma aprovação vale para esse conjunto exato ao alternar perfis. Alterar um arquivo verificado ou sua permissão de execução exige nova revisão. Enquanto isso, plugins globais selecionados continuam disponíveis.

O rodapé mostra a operação em andamento e o tempo decorrido durante instalação, atualização, remoção e reconexão. Aguarde a conclusão antes de fazer outra alteração.

Pressione u para atualizar uma instalação Git global gerenciada até o HEAD atual de sua origem. Pressione d para desinstalar um plugin global. Se o plugin alterado estiver selecionado pelo Extension Profile ativo, o Clarvis recompõe o backend; desinstalá-lo deixa esse Extension Profile visivelmente degradado até a referência ser removida ou o plugin ser instalado novamente. O Clarvis bloqueia atualização ou remoção de um plugin selecionado durante uma execução para que seu snapshot fixado não mude por baixo dela, e o kernel impede que uma nova execução dispute a mutação. Se um plugin selecionado for alterado por um cliente que não execute a reconexão da TUI, esse kernel desatualizado recusa execuções posteriores até /reconnect. Plugins do workspace fazem parte do repositório, então remova-os do próprio repositório. Um symlink para um checkout externo continua visível e ativável, mas o Clarvis não oferece nem executa atualização gerenciada nesse destino vinculado.

O plugin é ativado como um conjunto

O plugin é selecionado como uma unidade: agentes, skills, servidores MCP, hooks e serviços entram e saem juntos. Se o conteúdo instalado mudar depois, o Clarvis mantém o novo snapshot fora de uma execução ativa e pede revisão antes que ele entre; uma execução em andamento nunca muda por baixo. O snapshot inclui os bytes e o modo executável dos arquivos de processo locais do pacote referenciados diretamente por MCPs, hooks e capacidades, não apenas suas declarações no manifesto.

Crie um plugin

Um plugin convencional pode ser tão pequeno quanto este:

quality-kit/
├── plugin.json
├── agents/
│   └── reviewer.md
├── skills/
│   └── quality-check/
│       └── SKILL.md
└── hooks/
    └── hooks.json

Coloque plugin.json na raiz do plugin. Os nomes usam letras minúsculas, números, sublinhados e hifens. Uma instalação Git usa o name do manifesto como diretório de instalação. Em um layout multi-host já instalado, o diretório é o namespace de execução; o Clarvis pode derivar dele um name ausente no manifesto:

{
  "name": "quality-kit",
  "version": "0.0.1",
  "description": "Agentes, skills e verificações voltados à revisão.",
  "author": {
    "name": "Acme Engineering"
  },
  "mcpServers": {
    "checks": {
      "type": "stdio",
      "command": "quality-kit-mcp",
      "args": ["--stdio"],
      "resources": false
    }
  },
  "hooks": [
    {
      "event": "pre_finalize",
      "command": "bun run lint",
      "timeout_ms": 60000,
      "on_failure": "deny"
    }
  ],
  "bootstrapSkill": "quality-check",
  "capabilityRunPolicies": {
    "plans": {
      "skills": {
        "quality-check": "review"
      }
    }
  }
}

O único campo obrigatório do manifesto nativo é name. Se estiver presente, version deve ser uma string não vazia. Você pode declarar hooks diretamente no manifesto, como acima. Quando o manifesto não declara hooks, o Clarvis também procura hooks/hooks.json. Os arquivos e diretórios relativos indicados por um manifesto precisam permanecer dentro do plugin.

Para um plugin compatível com vários hosts, o Clarvis aceita um plugin.json na raiz e manifestos em diretórios com o formato .<host>-plugin/plugin.json. Um manifesto raiz que declare o schema portátil de Agent Plugins é prioritário. Caso contrário, .clarvis-plugin/plugin.json é prioritário quando existe; sem nenhum dos dois, o Clarvis seleciona o único manifesto legível que declara a superfície de contribuições compatíveis mais rica. Ele nunca combina dois manifestos de hosts. Declare locais de skills em skills como um diretório relativo ou uma lista. Cada local pode ser uma coleção ou um diretório individual que contém SKILL.md. O Clarvis mantém no máximo quatro raízes efetivas de varredura; uma lista exaustiva de skills irmãs pode ser representada pelo diretório pai sem tornar visível uma irmã não declarada. Declare servidores MCP diretamente, indique um documento complementar em mcpServers ou omita essa chave e use .mcp.json ou mcp.json por convenção.

Use pacotes Agent Plugin e Codex diretamente

O Clarvis reconhece o pacote portátil Agent Plugins v1 sem conversão. Um plugin.json na raiz com o schema canônico de Agent Plugins é prioritário, usa os componentes fixos skills/ e mcp.json da raiz e aplica as regras de manifesto de Agent Skills:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "quality-kit",
  "version": "preview"
}

Cada filho imediato de skills/ deve conter SKILL.md com a grafia exata. Nomes de skills portáteis usam segmentos alfanuméricos minúsculos separados por hífens simples, têm no máximo 64 caracteres e coincidem com seu diretório. O Clarvis também valida os campos license, compatibility, metadata com valores string e allowed-tools separado por espaços do contrato Agent Skills. O mcp.json da raiz pode declarar servidores stdio, streamable-http ou sse. Servidores stdio recebem PLUGIN_ROOT e PLUGIN_DATA gerenciados pelo cliente; esses dois placeholders são expandidos uma vez nos argumentos, ambiente e diretório de trabalho. Dados persistentes do plugin ficam no estado do Clarvis, fora do checkout instalado, e sobrevivem a uma atualização. Um documento MCP inválido desativa apenas MCP. Um servidor inválido, inclusive quando ultrapassa um limite do host Clarvis após a normalização, é descartado individualmente; um servidor ou uma skill inválida nunca remove os outros componentes válidos.

Pacotes no estilo Codex também são carregados no lugar: .codex-plugin/plugin.json, .mcp.json na raiz, agents/ e skills/ não precisam ser reempacotados. Caminhos relativos ao manifesto, como ../skills, são resolvidos a partir de .codex-plugin/ sem sair do pacote.

O .mcp.json pode ser um mapa direto de servidores ou envolvê-lo em mcpServers ou mcp_servers. Um servidor com url e sem transporte explícito se torna HTTP, http_headers vira headers e os campos OAuth compatíveis em camel case são normalizados para o formato snake case do Clarvis. Os valores MCP de um Agent Plugin portátil expandem apenas os placeholders PLUGIN_ROOT e PLUGIN_DATA, pertencentes ao host, antes de desabilitar a expansão geral; referências explícitas a credenciais continuam sendo resolvidas pela fronteira normal de credenciais do Clarvis.

Mapeie com segurança um valor userConfig de outro host

Um manifesto de outro host pode declarar uma configuração de usuário string e mapeá-la para o valor inteiro de uma variável de ambiente de um servidor stdio:

{
  "userConfig": {
    "apiKey": { "type": "string" }
  },
  "mcpServers": {
    "service": {
      "command": "service-mcp",
      "env": {
        "SERVICE_TOKEN": "${user_config.apiKey}"
      }
    }
  }
}

O Clarvis traduz esse valor exato para ${SERVICE_TOKEN} e obtém o valor do ambiente do operador; ele nunca importa um padrão ou marcador de segredo do manifesto. Referências embutidas, argumentos de comando, headers, configurações não declaradas ou que não sejam strings e servidores com expandVariables: false retêm apenas o servidor MCP afetado. As contribuições irmãs válidas continuam disponíveis.

Documentos de hooks compatíveis e organizados por evento podem estar envolvidos por um objeto hooks, ser referenciados por caminho ou ficar em hooks/hooks.json. O Clarvis traduz nomes de eventos, seletores de ferramentas, marcadores da raiz do plugin, timeouts e decisões compatíveis para as mesmas definições normalizadas usadas por um manifesto nativo. O que não puder ser traduzido é informado nos detalhes do plugin, sem ampliar silenciosamente um seletor. Se um comando traduzido começar com um executável relativo, como ./hooks/session-start.cmd, o Clarvis ancora esse executável à raiz instalada do plugin. O hook continua recebendo o workspace como diretório de trabalho, portanto qualquer operação relativa ao projeto permanece explícita.

Hooks de comando de plugins recebem PLUGIN_ROOT e PLUGIN_DATA, além dos aliases compatíveis CODEX_PLUGIN_ROOT e CODEX_PLUGIN_DATA. Hooks de ciclo de vida traduzidos preservam comandos Windows compatíveis, execução assíncrona, texto de status, limites de saída e chamadas diretas a mcp_tool. Entradas de hook de prompt ou agente sem suporte são informadas e ignoradas, sem serem executadas com autoridade mais ampla.

bootstrapSkill nomeia uma skill deste plugin cujo corpo deve estar disponível antes de o modelo responder. A política de plano review solicita uma revisão de planejamento nessa skill quando tanto a skill quanto o provedor de Plans selecionado vêm deste plugin.

Entenda nomes e identidades exatas

O Clarvis qualifica as contribuições que precisam ser globalmente únicas:

• agentes se tornam <plugin>:<agent>;
• servidores MCP se tornam <plugin>:<server>, e suas ferramentas se tornam <plugin>:<server>.<tool>;
• skills preservam o nome da skill e seguem a precedência normal de skills.

Por exemplo, o manifesto acima fornece o namespace MCP quality-kit:checks. Um agente chamado reviewer.md é referenciado como quality-kit:reviewer. Habilitar o plugin disponibiliza para todos os agentes efetivos, nas próximas execuções, cada ferramenta realmente anunciada por quality-kit:checks; não é preciso editar um perfil de agente para aderir a esse servidor MCP. O agent profile salvo permanece inalterado. Se as configurações globais ou do workspace substituírem esse namespace MCP exato, a declaração do operador prevalece e continua disponível apenas para profiles que selecionem suas ferramentas; ela não herda a concessão automática do plugin.

Plugins globais podem ficar em ~/.agents/plugins/<name> ou ~/.clarvis/plugins/<name>. Um repositório pode conter plugins de workspace em .agents/plugins/<name> ou .clarvis/plugins/<name>. Os quatro inventários são igualmente descobertos e ativáveis com ou sem um Extension Profile personalizado. Cada referência é exata: { scope, source, name }, com source igual a agents ou clarvis. Uma instalação de mesmo nome nunca oculta nem substitui outra; selecionar duas ao mesmo tempo é inválido porque os namespaces de contribuições usam o nome do plugin. Suas instalações podem ser diretórios ou symlinks para um diretório compartilhado de plugin; todos os caminhos contribuídos continuam confinados ao pacote resolvido. Checkouts externos vinculados são apenas descobertos e devem ser atualizados no repositório que os possui. Suas configurações globais e do workspace sempre prevalecem sobre as contribuições dos plugins.

Identidade upstream de autor ou publisher, licença, homepage, repositório e URLs legais, palavras- chave, descrições de capacidades e prompts, categoria, cores e assets de interface limitados continuam disponíveis nos detalhes do plugin. São apenas metadados de apresentação: nunca concedem ferramentas, iniciam processos ou ignoram a confiança.

Recursos empacotados de skills entram no fingerprint com limites de 8 MiB por arquivo e 32 MiB no total por plugin. A fronteira de execução de helpers é o diretório da própria skill, não a coleção ou o plugin inteiro, e a dependência MCP opcional do sidecar precisa nomear um servidor realmente disponível no Extension Profile ativo.

Saiba o que o Clarvis aceita

settings.json é estrito: uma configuração de nível superior desconhecida causa um erro. plugin.json é intencionalmente tolerante para que um plugin compatível com várias ferramentas não seja rejeitado apenas por conter metadados externos. O Clarvis informa as chaves desconhecidas do manifesto, mas não age com base nelas. Uma chave digitada incorretamente pode, portanto, deixar uma contribuição inativa mesmo que o plugin seja carregado. Revise as observações no navegador de plugins.

Habilite apenas código em que você confia

Plugins podem fornecer servidores MCP executáveis, agentes com permissões próprias, serviços de capacidades e hooks executados com seus privilégios. Instalar por Plugins é o consentimento para essa unidade completa. Plugins controlados pelo repositório ainda exigem revisão do fingerprint exato do workspace antes que seu conteúdo alterado possa entrar.

Veja também

• Extension Profiles
• Marketplaces
• Hooks
• Skills
• Servidores MCP
• Referência de extensões