Mods e hooks no Claude Code: diferenças e quando usar

Settings hooks: scripts fora do processo

Um settings hook é um comando de shell, uma requisição HTTP, uma chamada de ferramenta MCP, um prompt ou um agente que roda em um ponto do ciclo de vida da sessão. Você declara esse hook em um arquivo JSON de configuração, como o settings.json.

A cada evento, o Claude Code inicia o processo, envia um JSON pela entrada padrão e lê a resposta pela saída padrão ou pelo código de saída. Em seguida, o processo termina e nada fica em memória.

Os eventos mais usados são PreToolUse, PostToolUse, UserPromptSubmit, Stop e SessionStart. Além deles, existem eventos para compactação, subagentes, worktrees, notificações e troca de modelo.

O escopo depende do arquivo onde a configuração mora. O ~/.claude/settings.json vale para todos os projetos, enquanto o .claude/settings.json fica no repositório e pode ser compartilhado com o time.

Mods: funções dentro do processo

Um mod é um plugin cujo comportamento mora em um módulo JavaScript ou TypeScript. O Claude Code carrega esse módulo uma única vez, e ele permanece vivo durante toda a sessão.

Dessa forma, o mod consegue guardar estado, desenhar interface e chamar o próprio Claude Code de volta. Por exemplo, ele abre um painel, registra um comando de barra, executa um processo ou oferece uma ferramenta nova para o modelo.

Se você quer construir o primeiro do zero, o artigo como criar seu primeiro mod mostra o passo a passo completo.

Exemplo de settings hook que bloqueia rm -rf

Este trecho do .claude/settings.json executa um script apenas quando o Bash recebe um comando que começa com rm:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

O script lê o JSON da entrada padrão, extrai o comando e nega a execução quando encontra rm -rf:

#!/bin/bash
# lê o comando enviado pelo Claude Code
COMMAND=$(jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0  # sem decisão, segue o fluxo normal de permissões
fi

Repare que o script não sabe nada sobre a sessão anterior nem sobre o próximo evento. Cada chamada nasce e morre isolada, o que torna o modelo simples e previsível.

Um detalhe importa bastante: o código de saída 1 não bloqueia nada. Portanto, se o hook existe para impor uma política, use sempre exit 2 ou o JSON com deny.

Outro ponto de atenção é o tempo de execução. O UserPromptSubmit roda antes de cada prompt e tem timeout padrão de 30 segundos, então um script lento trava a sessão inteira.

Ainda assim, quem compara mods e hooks no Claude Code costuma subestimar o quanto esse modelo resolve sozinho. Linters, formatadores, auditoria e bloqueios simples cabem perfeitamente em um script de poucas linhas.

A cadeia de middleware com next

Para quem vem do .NET, entender a cadeia é a chave para comparar mods e hooks no Claude Code.

Os hooks de mods formam uma cadeia, como um middleware de ASP.NET Core ou Express. O seu hook roda, chama next(e), os outros plugins recebem o evento e, no fim, o Claude Code executa o comportamento padrão.

Com isso, um hook de mod tem três movimentos possíveis:

• Observar: chama await next(e), olha o resultado e devolve sem alterar nada.
• Reescrever: chama next({ ...e, command: safer }) com uma versão modificada do evento.
• Responder: devolve { deny: "..." } sem chamar next, assumindo o evento por conta própria.

O mesmo bloqueio de rm -rf fica assim como mod:

// hooks/guard.mjs
export function register(on) {
  on("tool.call", { tool: "Bash" }, async ($, e, next) => {
    const command = String(e.command ?? "");
    if (command.includes("rm -rf")) {
      // responde o evento sem repassar para o Claude Code
      return { deny: "Destructive command blocked by guard mod" };
    }
    return next(e);
  });
}

O resultado parece igual ao do settings hook, contudo a execução muda bastante. Aqui não existe processo novo, não existe JSON pela entrada padrão e o hook tem acesso a todo o contexto da sessão.

Estado que sobrevive ao hot reload

O mod Token Weather, apresentado no blog oficial, mostra bem essa diferença. Ele lê o uso da janela de contexto após cada turno e desenha uma previsão do tempo acima do prompt.

Variáveis de módulo parecem a escolha óbvia para guardar o histórico, porém cada salvamento recarrega o arquivo e zera tudo. Por isso, o exemplo usa $.state, que o host mantém durante a sessão inteira:

// o host guarda este valor, então ele sobrevive ao hot reload
const readings = { plugin: "token-weather", key: "readings" };

async function takeReading($) {
  const { context } = await $.session.usage();
  if (!context?.window) return;
  const { value: history = [] } = await $.state.get(readings);
  await $.state.set(readings, [...history, context.percent].slice(-12));
}

Além disso, um $.state.get feito durante um ui.render inscreve o desenho, e cada $.state.set posterior redesenha a interface sozinho. Um settings hook simplesmente não tem onde guardar esse histórico nem onde exibi-lo.

Para declarar esse valor, o plugin aponta no manifesto para um arquivo .d.ts com a interface PluginState. Se a declaração faltar, o validador acusa o erro e já indica a correção.

Tabela comparativa de mods e hooks no Claude Code

Segundo a documentação, o hook de um mod tem 10 segundos de tempo próprio por despacho. No entanto, o tempo gasto esperando dentro de uma chamada ao $ não entra nessa conta.

Esse detalhe permite segurar uma chamada enquanto o usuário decide. O mod Blast Radius usa exatamente esse truque para abrir um painel com os botões Proceed e Cancel antes de um rm -rf.

Onde cada um roda

Os settings hooks disparam no terminal, nas extensões de IDE, no app desktop e nas sessões na nuvem. Já os hooks de um mod rodam em todos esses lugares, mas o desenho aparece apenas no terminal e na aba Code do app desktop.

Na extensão do VS Code, no claude -p e no Agent SDK, o mod executa a lógica normalmente sem exibir nada. Além disso, sessões WSL no app desktop não carregam plugins, então nenhum mod roda ali.

Escolha um settings hook quando

O settings hook é a melhor opção quando você precisa permitir, bloquear ou registrar um evento com um script que já existe. Rodar um linter após cada Edit, por exemplo, é um caso clássico.

Ele também faz sentido quando o time não usa JavaScript, pois qualquer linguagem serve. Da mesma forma, um endpoint HTTP interno de auditoria se encaixa perfeitamente no type: "http".

Por fim, prefira o settings hook quando a política precisa valer em qualquer superfície, inclusive em sessões na nuvem. Só lembre que a nuvem não lê o seu ~/.claude/settings.json local. Nesse caso, a simplicidade do modelo de texto vira vantagem.

Escolha um mod quando

O mod entra em cena quando você quer um painel, uma faixa acima do prompt ou um comando de barra que responde na hora, sem gastar um turno do Claude. O Replay Theater, por exemplo, registra o comando /replay para navegar pelas edições do último turno.

Ele também é a escolha certa quando dois eventos precisam compartilhar dados. Um hook pode contar chamadas de ferramenta enquanto outro mostra a contagem ao lado do spinner.

Além disso, só o mod consegue reescrever partes da interface que o próprio Claude Code desenha, como a linha de uma chamada de ferramenta, o spinner ou a caixa de perguntas.

Na dúvida entre mods e hooks no Claude Code, faça uma pergunta: o usuário precisa ver ou clicar em algo?

Se a resposta for sim, o mod é o caminho. Funções nativas como o /diff e o suporte ao AGENTS.md já são mods, e o código fica público no repositório oficial.