Hooks — automação determinística

Hook é um script que dispara automaticamente em certos eventos do Claude Code: antes de usar uma ferramenta, depois de editar um arquivo, no fim da sessão. Diferente de skill e CLAUDE.md, hook não é sugestão — é código que roda.

Hook vs skill

A diferença crucial:

Skill/CLAUDE.md: advisory. É instrução que o modelo pode seguir ou não. Funciona na maioria das vezes. Falha silenciosamente quando o modelo ignora.
Hook: determinístico. Roda sempre, não depende do humor do modelo. Se o comando sair com código de erro, a ação é bloqueada.

Quer garantir que o prettier rode após toda edição? Hook. Quer que o Claude lembre de rodar prettier? Skill. A diferença é entre “com certeza” e “quase sempre”.

Eventos principais

PreToolUse: antes do Claude usar uma ferramenta (Edit, Bash, etc). Dá pra bloquear.
PostToolUse / PostEdit: depois que a ferramenta rodou. Útil pra formatar, rodar teste, auditar.
UserPromptSubmit: quando você manda prompt. Dá pra injetar contexto.
Stop: quando a resposta termina.

Caso 1: prettier automático

~/.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Todo arquivo que o Claude editar passa pelo prettier. Sem pedir, sem esquecer.

Caso 2: filtrar log gigante

Claude rodou kubectl logs e voltaram 50k linhas. Teu contexto explode. Hook de PreToolUse pode interceptar e processar:

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "~/.claude/hooks/filter-logs.sh"
        }
      ]
    }
  ]
}

O script lê o comando que o Claude quer rodar, e se for kubectl logs ou similar, roda com | tail -200 | grep -i error. O Claude recebe 30 linhas úteis em vez do dilúvio.

Caso 3: bloquear commit em `main`

#!/bin/bash
if echo "$CLAUDE_TOOL_INPUT" | grep -q "git commit" && \
   [ "$(git branch --show-current)" = "main" ]; then
  echo "Bloqueado: não commita direto em main" >&2
  exit 2
fi
exit 0

Exit code 2 no PreToolUse cancela a ação. Rede de segurança que não depende de “ah, esqueci”.

Quando NÃO criar hook

Pra coisa que só precisa acontecer às vezes — vira atrito
Pra substituir um linter/CI que já existe — deixa o CI fazer o trabalho
Quando uma skill resolveria e o custo de falhar é baixo

Hook é faca afiada: poderoso, mas se configurar errado te bloqueia de trabalhar.

Dica prática

Logga o que teus hooks fazem nos primeiros dias (echo "hook X rodou em $CLAUDE_FILE_PATH" >> ~/.claude/hook.log). Hook silencioso que falha é frustrante de debugar — ter o log pronto salva horas.