Mods ou hooks no Claude Code: qual a diferença e quando usar cada um?

Fala aí, beleza? Se tu já configura hook no Claude Code, se liga nisso: na documentação, o handler de um mod e o hook do arquivo de settings usam a mesma palavra (hook), mas NÃO são a mesma coisa 😀

Os mods chegaram na versão 2.1.287, lançada em 1 de outubro de 2026, e já vêm ativados por padrão

Aí bate a dúvida: se eu já tenho meus hooks no settings.json, onde entra um mod nessa história?

Antes de tudo, a terminologia oficial, pra gente não se embolar:

• nas páginas de mods, hook é o handler de um mod
• o hook que você define no arquivo de settings se chama settings hook

Daqui pra frente vou usar exatamente esses dois nomes, beleza?

O que é um settings hook no Claude Code?

Recapitulando rapidinho, só pra ancorar a comparação

O settings hook vive em .claude/settings.json (nível do projeto) ou em ~/.claude/settings.json (global), conforme a documentação de hooks

Ele é configurado em três níveis:

1. Evento: quando ele dispara, como PreToolUse ou PostToolUse
2. Matcher: um filtro, por exemplo só para a ferramenta Bash
3. Handlers: o que roda de fato, podendo ser um ou mais

Os tipos de handler são command, http, mcp_tool, prompt e agent

E a diferença entre os dois eventos mais usados é simples:

• o PreToolUse roda antes da chamada de ferramenta e pode bloqueá-la
• o PostToolUse roda depois que a chamada dá certo

Tome cuidado com os timeouts padrão, que mudam por tipo: 600 s para command, http e mcp_tool, 30 s para prompt e 60 s para agent

Ou seja, o settings hook é um gatilho que chama algo de FORA do Claude Code: um comando shell, uma requisição HTTP, um prompt e por aí vai

O que é um mod no Claude Code (e onde ele empacota os hooks)?

Segundo a documentação de mods, um mod é um plugin que muda a aparência e o comportamento do Claude Code

Ele é feito de handlers de evento em JavaScript ou TypeScript, que o Claude Code chama quando algo acontece

E o handler pode fazer três coisas com o evento: observar, alterar ou assumir 🙂

Os eventos documentados são:

• tool.call: uma ferramenta está prestes a rodar
• prompt.submit: um prompt foi enviado
• ui.render: um render site está prestes a ser desenhado

Render site? Que bicho é esse?

É um ponto de extensão da interface, um lugar da tela onde o mod pode entrar e desenhar

Estrutura mínima de um mod:

Um mod pequeno tem só três arquivos:

• plugin.json: o manifesto do plugin
• hooks.json: aponta para o arquivo de código
• register.js: o código em si, que a doc chama de hooks module

O hooks module é o ponto de entrada do mod e exporta register(on, options)

Quando o mod carrega, o Claude Code chama o register e passa a função on, que recebe o nome do evento, um matcher opcional e o hook

O exemplo da documentação é este:

on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))

Repara que o matcher { tool: 'Bash' } faz o mesmo papel do matcher do settings hook: filtrar quando o hook dispara

A diferença é que aqui tudo é função JavaScript rodando DENTRO do processo do Claude Code

Se tu quer entender melhor essa ideia de plugin estendendo um agente, vale ver a comparação entre harness de plugins e agente que já fizemos aqui no blog

Mods funcionam na CLI do Claude Code e na aba Code do app Claude Desktop, e a instalação é pelo /plugin, nos dois casos

Mod vs settings hook: comparação lado a lado

Um ponto que não aparece na tabela, mas pesa MUITO: mod não roda em sandbox, ele tem o mesmo acesso à máquina que o próprio Claude Code

Falo disso com calma na seção de segurança, mais pra baixo

Por que os hooks de um mesmo mod compartilham variáveis?

Esse é o pulo do gato que faz o mod ser diferente de um monte de settings hooks soltos

Como todos os hooks do mod moram no mesmo arquivo, eles enxergam as mesmas variáveis do módulo

No exemplo oficial, existe uma variável let calls = 0 usada ao mesmo tempo pelo hook de tool.call e pelo de ui.render

Traduzindo: um hook conta as chamadas de ferramenta e o outro mostra essa contagem na tela, sem nenhuma gambiarra de arquivo temporário no meio, legal né? 😀

Com settings hooks, cada handler é um comando ou requisição separada, então essa ponte direta entre lógica e interface não existe

Variável de módulo ou $.state?

Aqui tem uma pegadinha que vale antecipar

Variável de módulo dura só até o módulo recarregar, e isso acontece sempre que tu salva um arquivo durante o desenvolvimento

Então ela serve para valores que podem ser perdidos sem drama

Já o $.state:

• dura até a sessão terminar ou até o usuário rodar /clear, /resume ou /branch
• sobrevive ao reload
• é reativo: um hook ui.render que lê um valor fica inscrito nele

Se o dado importa (e precisa aparecer atualizado na tela), vai de $.state

Se é contador de debug, variável de módulo resolve

O que só um mod consegue fazer na interface?

Settings hooks, skills, status lines e servidores MCP agem de fora do Claude Code

Repara que a status line aparece nessa lista e vai aparecer de novo logo abaixo: a status line tradicional age de fora, já com mod é o próprio mod que desenha a status line, de dentro do processo

O mod roda dentro, e por isso faz coisas que eles não fazem

Na interface, um mod pode desenhar:

• um painel ao lado do transcript
• uma faixa acima do prompt
• a status line

E também pode substituir elementos do próprio Claude Code:

• o spinner
• as linhas de chamada de ferramenta
• o diálogo de pergunta

Além da parte visual, o mod pode adicionar um comando para o usuário rodar ou uma ferramenta para o Claude chamar

Nada disso está ao alcance de um settings hook, que só decide sobre fluxo, argumentos, resultado e contexto

Quando usar settings hook e quando usar mod?

Bora pro critério prático, separado por tipo de necessidade

Use settings hook quando:

• precisa bloquear ou validar uma chamada de ferramenta antes dela rodar
• quer ajustar os argumentos ou o resultado de uma chamada
• quer injetar contexto para o Claude
• a lógica já existe como script shell ou endpoint HTTP e tu só quer plugar

Use mod quando:

• precisa desenhar algo na tela: painel, faixa acima do prompt, spinner
• quer criar um comando novo para o usuário ou uma ferramenta nova para o Claude
• precisa alterar turnos
• quer combinar lógica e interface com estado compartilhado entre os handlers

E tem uma regra oficial que vale gravar: se um settings hook, uma skill ou um servidor MCP já resolve o que você precisa, a documentação orienta usar essas opções antes de escrever um mod

Nada de criar mod só porque é a novidade da semana haha

Segurança e como desativar mods

Aqui é onde muita gente vai se ferrar se não prestar atenção…

Mods não rodam em sandbox: eles têm o mesmo acesso à máquina que o próprio Claude Code

E mais: com o sandboxing ativado, o sandbox isola os comandos Bash do Claude, mas um processo iniciado por um mod roda fora dele

Então instalar mod de origem duvidosa é tipo deixar um desconhecido rodar os rm -rf da vida no seu PC 😛

Como desligar mods:

1. Um mod específico: abra o /plugin, vá na aba Installed e desative ou desinstale o plugin
2. Todos os mods numa sessão: inicie o Claude Code com --safe-mode. O erro comum aqui é esquecer que essa flag também desliga outras personalizações, não só os mods
3. Todos os mods em qualquer sessão: coloque "disableAllHooks": true em ~/.claude/settings.json. O nome engana, mas lembra da terminologia lá do começo: nas páginas de mods, os handlers de um mod também se chamam hooks, por isso a chave fala em "hooks" e é ela que desativa todos os mods instalados

E em organizações?

Existe o allowManagedModsOnly, que impede que mods instalados pelo usuário carreguem

O resto de cada plugin (skills, comandos, agents e servidores MCP) continua funcionando normalmente

Veredito: mod ou hook?

No fim, mod e settings hook não são concorrentes, são camadas diferentes

O settings hook continua sendo a primeira escolha pra controlar o fluxo de ferramentas e prompts: bloquear, validar, ajustar, injetar contexto

O mod entra quando você precisa de interface, de comandos ou ferramentas novas, ou de lógica com estado compartilhado entre handlers

E aí tu aceita o custo de rodar algo sem sandbox, com o mesmo acesso do Claude Code à sua máquina

Se dá pra resolver com settings hook, resolve com settings hook 🙂

Próximo passo

Recapitulando o caminho pra colocar isso em prática:

1. Revise os settings hooks que você já tem e anote quais necessidades pedem interface ou estado compartilhado
2. Confirme que está no Claude Code 2.1.287 ou superior, que é o mínimo pra usar mods
3. Comece pelo mod de três arquivos: plugin.json, hooks.json e register.js
4. Use variável de módulo pra testar e migre pra $.state o que precisa sobreviver ao reload

O resto continua no settings.json, do jeito que já funciona

Curtiu? Bora trocar uma ideia sobre qual mod você vai criar primeiro

Até o próximo post!