⚡ O que sao Hooks (Event-Driven Shell Commands)
Hooks sao comandos shell executados automaticamente quando eventos especificos ocorrem durante o ciclo de vida de uma sessao do Claude Code. Diferente de skills (que voce invoca manualmente), hooks sao reativos e automaticos - disparam sem intervencao do usuario.
🎯 Conceito Principal
O modelo mental para hooks e simples: "Quando X acontecer, execute Y". Eles seguem o padrao event-driven:
- • Event-driven: Hooks respondem a eventos do ciclo de vida do Claude Code. Cada evento tem um nome especifico (PreToolUse, PostToolUse, SessionStart, etc.)
- • Shell commands: O que executa e um comando shell normal - qualquer coisa que voce rodaria no terminal pode ser um hook
- • Automaticos: Uma vez configurados, hooks disparam sozinhos. Nao e necessario lembrar de rodar nada manualmente
- • Encadeamento: Voce pode ter multiplos hooks para o mesmo evento. Eles executam em sequencia na ordem em que foram definidos
💡 Dica Pratica
Pense em hooks como git hooks para o Claude Code. Assim como pre-commit e post-commit no Git executam scripts automaticamente, hooks do Claude Code executam comandos em pontos especificos do ciclo de vida da sessao. Se voce ja usa git hooks, a logica e identica.
🔄 PreToolUse e PostToolUse
Os hooks PreToolUse e PostToolUse sao os mais usados e poderosos. Eles disparam antes e depois que o Claude executa qualquer ferramenta (tool), permitindo interceptar, validar e reagir a cada acao do agente.
🎯 Conceito Principal
O fluxo de execucao com hooks de tool:
- • PreToolUse - validacao: Use para validar antes da execucao. Exemplo: bloquear Write em arquivos protegidos, prevenir rm em diretorios criticos
- • PostToolUse - reacao: Use para reagir apos a execucao. Exemplo: rodar prettier depois de Write, executar testes depois de Edit
- • Filtragem por tool: Voce pode configurar hooks para dispararar apenas para tools especificas (Write, Edit, Bash) ou para todas
💡 Dica Pratica
O caso de uso mais comum e auto-format apos write: configure um PostToolUse que roda prettier --write no arquivo modificado. Assim, todo codigo gerado pelo Claude ja sai formatado. Outro classico: PreToolUse para bloquear escrita em .env e prevenir vazamento de segredos.
🚀 Hooks de Sessao (SessionStart, SessionEnd)
Os hooks SessionStart e SessionEnd disparam no inicio e no fim de cada sessao do Claude Code. Sao ideais para setup de ambiente, logging, metricas e limpeza automatica.
🎯 Conceito Principal
Casos de uso para hooks de sessao:
- • SessionStart - setup: Verificar pre-requisitos (Node, Docker rodando), carregar variaveis de ambiente, iniciar servicos necessarios, registrar inicio da sessao em um log
- • SessionEnd - cleanup: Salvar metricas da sessao (tokens usados, arquivos modificados), parar servicos temporarios, enviar resumo por Slack ou email
- • Logging: Registrar cada sessao com timestamp, duracao e acoes realizadas para auditoria e analise de produtividade
- • Metricas: Coletar dados sobre uso do Claude Code para otimizar workflows e justificar investimento na ferramenta
💡 Dica Pratica
Um SessionStart simples mas poderoso: verificar se o branch atual e o correto antes de comecar a trabalhar. Isso previne o erro classico de modificar codigo no branch errado. Outro uso: exibir um lembrete das tasks pendentes do projeto ao iniciar uma nova sessao.
🔔 Hooks de Notificacao (NotificationSend)
O hook NotificationSend permite interceptar e customizar as notificacoes que o Claude Code envia. Voce pode redirecionar notificacoes para Slack, Discord, email ou qualquer outro sistema de comunicacao da sua equipe.
🎯 Conceito Principal
O NotificationSend dispara quando o Claude precisa notificar o usuario sobre algo. Voce pode interceptar e redirecionar:
- • Redirecionamento: Envie notificacoes para Slack, Discord, Telegram, email ou qualquer webhook. Ideal para tarefas longas em background
- • Filtragem: Filtre notificacoes por tipo ou conteudo. Receba apenas alertas criticos no celular e o resto no desktop
- • Enriquecimento: Adicione contexto extra as notificacoes, como nome do projeto, branch atual ou duracao da tarefa
💡 Dica Pratica
O caso de uso mais valioso: notificacao quando uma tarefa longa termina. Se voce pediu ao Claude para refatorar 50 arquivos e foi tomar cafe, o hook de notificacao avisa no Slack quando terminou. Isso transforma o Claude Code de uma ferramenta interativa em um assistente assincrono.
⚙️ Configurando Hooks em settings.json
Hooks sao configurados no arquivo settings.json do Claude Code. A estrutura e declarativa: voce define o evento, o comando e opcoes adicionais como filtros e timeouts.
🎯 Conceito Principal
Estrutura completa de configuracao de hooks no settings.json:
- • matcher: Filtra por nome da tool. Use "Write", "Edit", "Bash" ou deixe vazio para todas
- • command: O comando shell a executar. Variaveis de ambiente do contexto estao disponiveis ($FILE_PATH, $TOOL_NAME, etc.)
- • timeout: Tempo maximo de execucao em milissegundos. Hooks que demoram muito podem travar a sessao
💡 Dica Pratica
Sempre defina um timeout para hooks. Um hook sem timeout que trava pode congelar toda a sessao do Claude Code. Comece com timeouts generosos (10s) e reduza conforme necessario. Para hooks de formatacao, 5 segundos e suficiente. Para hooks que fazem requests HTTP, use 15-30 segundos.
🎯 Casos de Uso Praticos (Auto-Format, Auto-Lint, Notifications)
Os tres casos de uso mais populares de hooks sao auto-format, auto-lint e notificacoes. Juntos, eles transformam o Claude Code em um agente que nao apenas gera codigo, mas garante qualidade e mantém voce informado automaticamente.
🎯 Conceito Principal
| Caso de Uso | Hook | Comando |
|---|---|---|
| Auto-format | PostToolUse (Write) | prettier --write $FILE |
| Auto-lint | PostToolUse (Write/Edit) | eslint --fix $FILE |
| Notificacao | NotificationSend | curl $SLACK_WEBHOOK |
| Bloquear .env | PreToolUse (Write) | test ! "$FILE" = ".env" |
| Auto-test | PostToolUse (Write) | npm test -- --related $FILE |
💡 Dica Pratica
Comece com auto-format apenas. E o hook de menor risco e maior retorno. Depois de validar que funciona bem, adicione auto-lint. Por ultimo, configure notificacoes. Essa progressao gradual evita surpresas e permite debugar cada hook isoladamente.
Exercicio Pratico
Hora de implementar hooks funcionais. Voce vai criar um par PreToolUse + PostToolUse que valida e formata codigo automaticamente.
Exercicio: Criar Hook PreToolUse + PostToolUse Funcional
Tempo estimado: 20-30 minutos
Criar o settings.json com hooks
Configure um PreToolUse que bloqueia escrita em .env e um PostToolUse que formata:
{
"hooks": {
"PreToolUse": [{"matcher": "Write", "command": "echo $FILE_PATH | grep -qv '.env'"}],
"PostToolUse": [{"matcher": "Write", "command": "npx prettier --write $FILE_PATH"}]
}
}
EOF
Testar o PreToolUse (bloqueio)
Peca ao Claude para escrever em .env e verifique se o hook bloqueia:
Testar o PostToolUse (formatacao)
Peca ao Claude para criar um arquivo JS sem formatacao e verifique se prettier roda automaticamente:
Validar os resultados
Confirme que: 1) .env foi bloqueado pelo PreToolUse, 2) test.js foi formatado automaticamente pelo PostToolUse apos a criacao.
✅ Criterios de Sucesso
📋 Resumo do Modulo
Proximo Modulo:
5.8 - Subagentes e /simplify /batch (2026)