Hooks
~30 min Intermediário Parte 2

Hooks

Automatize comportamentos com scripts que executam em resposta a eventos do Claude Code — antes e depois de cada ferramenta, no início de sessão e muito mais.

Hooks são scripts que o Claude Code executa automaticamente em resposta a eventos. Eles permitem criar pipelines de automação: logar operações, rodar linters, enviar notificações, injetar contexto e até bloquear ações potencialmente perigosas.

Tipos de hooks disponíveis

Hook Quando executa Pode bloquear?
PreToolUse Antes de usar uma ferramenta Sim (exit 1)
PostToolUse Após o uso de uma ferramenta. Recebe o resultado como variável. Não
SessionStart Ao iniciar uma nova sessão do Claude Code Não
SessionEnd Ao encerrar a sessão Não
UserPromptSubmit Ao submeter um prompt. Pode modificar ou enriquecer o contexto. Não
Stop Quando o Claude termina de gerar uma resposta Não

Configuração de hooks no settings.json

Hooks são configurados dentro do settings.json usando a chave hooks. Cada hook tem um matcher (qual ferramenta disparar) e uma lista de comandos:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Executando: $TOOL_INPUT' >> ~/.claude/logs/bash.log"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Arquivo escrito: $TOOL_RESULT' >> ~/.claude/logs/writes.log"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "echo '=== Nova sessão: $(date) ===' >> ~/.claude/logs/sessions.log"
          }
        ]
      }
    ]
  }
}

Hook com bloqueio (PreToolUse)

Um hook PreToolUse pode bloquear a execução retornando exit code 1. Isso permite criar guardas de segurança customizados:

{
  "PreToolUse": [
    {
      "matcher": "Bash",
      "hooks": [
        {
          "type": "command",
          "command": "node ~/.claude/hooks/check-dangerous-commands.js"
        }
      ]
    }
  ]
}
O script retorna exit code 0 para permitir a operação ou exit code 1 para bloqueá-la. Isso permite criar guardas de segurança customizados.

Variáveis disponíveis nos hooks

Variável Descrição
$TOOL_NAME Nome da ferramenta sendo usada (Bash, Write, etc.)
$TOOL_INPUT Input enviado para a ferramenta
$TOOL_RESULT Resultado retornado (disponível apenas em PostToolUse)
$SESSION_ID Identificador único da sessão atual
$PROJECT_ROOT Caminho absoluto do diretório do projeto

Casos de uso reais

Log de auditoria

Logar todos os comandos bash executados pelo Claude para compliance e debugging.

Lint automático

Rodar ESLint automaticamente após cada Write em arquivos .ts ou .tsx.

Git commit automático

Auto-commit após certas operações de escrita em arquivos de configuração.

Notificações

Notificar no Slack ou Discord quando uma tarefa longa for concluída.

Injeção de contexto

Adicionar informações da empresa, sprint atual ou dados de ambiente no SessionStart.

Exercício: hook de formatação automática

Objetivo

Criar hook PostToolUse que roda prettier --write automaticamente após cada Write em arquivos .ts ou .tsx.

Solução

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "if [[ '$TOOL_INPUT' == *.ts || '$TOOL_INPUT' == *.tsx ]]; then npx prettier --write \"$TOOL_INPUT\"; fi"
          }
        ]
      }
    ]
  }
}

Recursos

0%