Como revisar um mod do Claude Code antes de instalar no projeto do cliente

Um mod do Claude Code roda com o MESMO acesso à máquina que o próprio Claude Code, e sem sandbox nenhuma

Quando o projeto aberto é de cliente, isso pesa (e muito)

Fala aí, beleza? Em 2026-10-01 a Anthropic abriu o Claude Code para mods, que são handlers em JavaScript ou TypeScript

Eles rodam dentro do Claude Code e mudam como ele se comporta e o que ele desenha na tela 😀

É muito massa pra customizar

Só que a própria documentação de mods é direta: instale só de fontes confiáveis

E confiar não é uma sensação, confiar vem de revisar…

Neste post te conto como ler um mod antes de deixar ele rodar no projeto: o que olhar, do que desconfiar e como desligar se der ruim

O que um mod do Claude Code pode fazer no seu projeto?

Um mod é um conjunto de handlers de eventos

Que evento? Pode ser uma chamada de ferramenta, um prompt enviado ou uma parte da interface sendo desenhada

Quando isso acontece, o Claude Code chama o handler, e o handler pode observar, alterar ou assumir o controle do evento

Na prática, um mod pode:

• reescrever um prompt
• adicionar UI nova
• substituir um recurso nativo
• adicionar funcionalidade nova
• segurar uma chamada de ferramenta enquanto pergunta algo pra você
• responder a chamada sem executar a ferramenta
• mandar a requisição para outro modelo

Pra mexer em arquivo, processo e rede, ele usa a API de mods, escrita como $

Essa API roda com as mesmas permissões do usuário que está rodando o Claude Code:

• $.fs: read, write, exists, stat e list
• $.process: run (ex: run(['git','status'])) e spawn
• $.http: fetch(url, init) sobre http ou https

Tem mais um detalhe: o mod que tu instala vive dentro de um plugin e entra pelo comando /plugin, como qualquer plugin

Existem também os mods nativos (built-in), que são outra categoria e a gente volta neles lá na parte de desligar mod

E um plugin instalado pode executar código arbitrário com os privilégios do seu usuário, além de trazer conteúdo que entra no contexto do Claude como instrução

Agora pensa no repositório do cliente aberto aí

Tudo que o seu usuário consegue ler, o mod também consegue: código, arquivo de configuração, credencial que estiver acessível e por aí vai

Por isso a revisão não é frescura 🙂

Por que o marketplace não garante que o mod é seguro?

Tropeço clássico: achar que está tudo certo só porque o mod veio de um marketplace com nome bonito

O nome do marketplace diz QUEM publica o catálogo, e não o que cada plugin faz

O aviso oficial na página de segurança de plugins é claro: a Anthropic não controla quais servidores MCP, arquivos ou outros softwares vêm nos plugins

Ela também não pode verificar se eles vão funcionar como esperado, nem se não vão mudar depois

Por isso a documentação manda revisar o plugin antes de instalar, seja qual for o marketplace

Se você conhece NPM, a lógica é parecida: o registro hospeda o pacote, mas quem tem que ler o que vai rodar é você

Antes de começar a revisão:

O que tu precisa ter em mãos:

• Claude Code no CLI ou no app desktop (mods funcionam nos dois)
• acesso ao diretório do plugin/mod, pra ler os arquivos
• noção básica de JavaScript ou TypeScript (não precisa ser ninja, precisa saber achar uma chamada de função)

E uma postura que vale ouro: faça a revisão FORA do repositório do cliente

Se precisar abrir uma sessão do Claude Code pra olhar o painel de detalhes, abre numa pasta neutra, sem o código do cliente ali do lado

Passo a passo para revisar um mod do Claude Code

São cinco passos, do mais rápido ao mais minucioso

Bora ver na prática?

1. Ver de onde vem o marketplace

No shell, roda:

claude plugin marketplace list

Ele mostra a origem de cada marketplace adicionado, que pode ser um repositório GitHub ou um diretório

O erro comum deste passo: confiar no nome do marketplace e nem olhar a origem (o nome é só um rótulo, o que importa é a origem)

2. Abrir a revisão sem instalar

Dentro de uma sessão, roda:

/plugin install <plugin>@<marketplace>

Esse comando NÃO instala na hora

Ele abre o painel /plugin nos detalhes do plugin, pra você revisar e escolher o escopo antes de instalar

No painel tem a seção ‘Will install’, que lista commands, agents, skills, hooks e servidores MCP e LSP do plugin

O erro comum deste passo: achar que a seção ‘Will install’ basta, porque ela só mostra que um hook EXISTE, não o que ele executa

3. Ler os arquivos que a documentação manda

No diretório do plugin, abre estes arquivos:

• .claude-plugin/plugin.json: o manifesto, que todo mod exige
• hooks/hooks.json: o comando que cada hook roda e o campo modules, um array com o caminho pro módulo de hooks (é por ali que tu descobre qual arquivo JS/TS ler)
• .mcp.json: o comando ou a URL de cada servidor
• todos os arquivos de bin/

O erro comum deste passo: pular a pasta bin/ e ler só os JSON

A documentação diz TODOS os arquivos de bin/, e não é à toa

4. Rodar o validate

claude plugin validate ./pasta-do-mod

Ele lê o manifesto e o módulo de hooks sem executar o código e sem abrir sessão

E roda a mesma análise estática que o Claude Code roda ao carregar um mod

Ou seja, dá pra olhar o mod por dentro sem dar play 🙂

O comando aceita duas flags:

• --strict trata aviso como erro
• --json gera um relatório legível por máquina

O erro comum deste passo: a validação passou e o leitor conclui que o mod é seguro

Não é bem assim! O validate mostra o que o mod faz, ele não julga a intenção

5. Ler as linhas hooks: e calls:

Na saída do validate, duas linhas são o coração da revisão:

• hooks: lista os eventos que o módulo intercepta, com um filtro entre chaves
• calls: lista todos os métodos da API de mods que ele chama

A pergunta é simples: isso combina com o que o mod promete fazer?

O erro comum deste passo: olhar só o nome do evento e ignorar o filtro entre chaves, que mostra o recorte daquele evento que o mod está pegando

Que instruções de um mod merecem desconfiança?

Aqui a régua é sempre a mesma: comparar a promessa com o comportamento

Se liga nos sinais mais comuns:

Sobre o tool.check, um detalhe importante

Um mod pode reestilizar boa parte da interface, mas não o prompt de permissão, então ele não consegue mudar o que esse prompt mostra

Mesmo assim, ele pode decidir ANTES do prompt aparecer, e é isso que pede atenção

Sobre desviar pra outro modelo: trocar o modelo que atende o projeto deveria ser uma decisão sua, com checklist, igual numa migração para o GPT-6 Astra, e não algo escondido dentro de um handler

Tem também uma boa notícia que deixa a linha hooks: confiável de ler

O nome do evento em cada chamada on() precisa ser uma string literal, tipo 'tool.call'

Se o autor tentar usar variável ou loop sobre uma lista de nomes, a validação falha

Ou seja, não dá pra esconder evento atrás de um nome montado em tempo de execução 😀

O que um mod pode mudar depois da revisão do classificador?

Esse é o ponto menos óbvio do post todo

O Claude Code tem um classificador no servidor que revisa a chamada de ferramenta

Só que, se um hook muda o input da tool call DEPOIS dessa revisão, ela não cobre o que vai rodar

Isso vale pra tool.call ou turn.step de mod, e também pra PreToolUse de settings

Traduzindo: o que foi revisado pode não ser o que executa…

Por isso o passo 5 é tão importante

Se a linha hooks: mostra tool.call ou turn.step, abre o módulo e procura onde o input é alterado

E cruza com a linha calls: pra ver o que mais o mod faz com aquilo

Como desligar ou remover um mod suspeito

Deu ruim ou bateu a dúvida? Tu tem duas saídas rápidas

1. Abrir uma sessão com os mods desligados

claude --safe-mode

Isso inicia uma sessão com todos os mods instalados desligados

Também ficam de fora CLAUDE.md, skills, plugins, hooks, servidores MCP e comandos/agents customizados

Autenticação, modelo, ferramentas nativas e permissões continuam funcionando normal

2. Desativar ou desinstalar o mod específico

No /plugin, vai na aba Installed e desativa ou desinstala o plugin individualmente

O erro comum deste passo: achar que disableAllHooks, --bare ou --safe-mode param TUDO

Eles param os mods instalados, mas não afetam os mods nativos (built-in)

Correções de segurança recentes envolvendo mods

Em outubro de 2026 saiu uma release com duas correções ligadas a mods

• em máquinas gerenciadas, uma aprovação anterior de mod mantinha aberta uma regra deny/ask em parte de um comando shell composto
• um mod instalado pelo usuário podia descarregar um plugin da organização

O recado é simples: mantenha o Claude Code atualizado, ainda mais na máquina onde mora código de cliente

Checklist final antes de liberar um mod no projeto do cliente

Recapitulando:

• conferiu a origem com claude plugin marketplace list
• abriu o painel de revisão com /plugin install sem instalar no impulso
• leu .claude-plugin/plugin.json, hooks/hooks.json, .mcp.json e TODOS os arquivos de bin/
• rodou claude plugin validate e leu as linhas hooks: e calls:
• comparou eventos e chamadas com o que o mod promete
• olhou com carinho tool.call, prompt.submit, tool.check, turn.step, rede, processo e escrita
• sabe usar claude --safe-mode e a aba Installed caso precise voltar atrás

E vale a pergunta de sempre: esse mod resolve um problema real?

Se a ideia é ganhar velocidade, antes de tudo vale medir se o Claude Code acelera o seu fluxo do jeito que está

Próximo passo: antes de instalar o próximo mod, roda claude plugin validate nele, e instala só de fonte confiável

No projeto do cliente, cinco minutos de leitura valem MUITO mais que uma explicação constrangedora depois haha

Até o próximo post!