Tutorial de hooks do Claude Code: 5 hooks de produção do zero

O Claude Code executa a ação correta na esmagadora maioria das vezes. Os casos extremos que sobram incluem force-push na main, pular o seu formatador e commitar código que não passa no lint. Os hooks eliminam esses casos extremos ao inserir barreiras determinísticas em 31 pontos do ciclo de vida do fluxo de trabalho do Claude (dados de agosto de 2026).¹ Este tutorial faz parte da minha série sobre AI engineering, dedicada à construção de sistemas de agentes em nível de produção. Eles disparam sempre, sem exceção, não importa como o prompt foi escrito nem como o modelo se comporta.

TL;DR: hooks são comandos de shell disparados por eventos do ciclo de vida do Claude Code.¹ Os hooks PreToolUse inspecionam e bloqueiam ações (código de saída 2 = bloquear, código 0 = permitir).² Os hooks PostToolUse validam e formatam depois do fato. Você os configura em .claude/settings.json com um matcher (um nome exato de ferramenta, uma lista separada por | ou uma expressão regular) e um array hooks aninhado.³ O tutorial abaixo constrói cinco hooks de produção: formatador automático, barreira de segurança, execução de testes, alerta de notificação e verificação de qualidade antes do commit.

Principais conclusões

• Pessoas que desenvolvem sozinhas: comece pelo formatador automático (hook 1) e pela barreira de segurança (hook 2). Esses dois hooks evitam os erros mais comuns do Claude Code sem nenhuma manutenção contínua.
• Líderes técnicos: versione os hooks no .claude/settings.json do repositório. Cada pessoa do time ganha automaticamente as mesmas barreiras de segurança e verificações de qualidade.
• Pessoas de segurança: o código de saída 2 bloqueia a ação.² O código de saída 1 apenas registra um aviso. Todo hook de segurança PreToolUse precisa usar exit 2, caso contrário ele não impõe nada.

O que são hooks?

Hooks são comandos de shell executados em eventos específicos do ciclo de vida de uma sessão do Claude Code. Eles rodam fora do LLM, como scripts comuns disparados pelas ações do Claude, e não como prompts interpretados pelo modelo.

Quatro categorias principais cobrem os usos mais comuns (o Claude Code documenta 31 tipos de evento em agosto de 2026):¹

• Eventos de sessão: SessionStart dispara quando uma sessão começa, SessionEnd quando ela é encerrada e Stop toda vez que o Claude termina uma resposta (não apenas no fim da sessão). Use-os para preparação, limpeza e notificações.
• Eventos de ferramenta: PreToolUse e PostToolUse disparam antes e depois de o Claude usar uma ferramenta (escrever um arquivo, rodar um comando bash ou buscar no código). São os hooks mais poderosos, porque conseguem inspecionar e bloquear ações específicas.
• Eventos de notificação: Notification dispara quando o Claude gera uma notificação. Útil para encaminhar alertas ao Slack, às notificações do desktop ou a sistemas de log.
• Eventos de subagente: SubagentStop dispara quando um subagente (iniciado pela ferramenta Agent) conclui o trabalho.⁴ Os hooks também disparam nas ações dos subagentes, então suas barreiras de segurança valem de forma recursiva.

A semântica dos códigos de saída importa.² O código 0 significa sucesso (siga em frente). O código 2 significa bloquear a ação. O código 1 é um erro de hook que não bloqueia nada: a ação acontece do mesmo jeito. Todo hook crítico para a segurança precisa usar exit 2 para que a barreira realmente valha.

O modelo mental: três tipos de garantia

Antes de escrever qualquer hook, pergunte-se: de que tipo de garantia eu preciso?

Garantias de formatação asseguram consistência depois do fato. Hooks PostToolUse em Write/Edit rodam o seu formatador após cada alteração de arquivo. O que o modelo produziu não importa, porque o formatador normaliza tudo. Esses hooks são idempotentes e podem rodar com segurança a cada edição.

Garantias de segurança impedem ações perigosas antes que elas aconteçam. Hooks PreToolUse em Bash inspecionam comandos e bloqueiam padrões destrutivos com o código de saída 2. Esses hooks precisam ser rápidos (abaixo de 500 ms), porque filtram toda chamada de ferramenta correspondente, e precisam usar o código 2 (não o 1), já que o código 1 só avisa, sem bloquear.

Garantias de qualidade validam o estado em pontos de decisão. Hooks PreToolUse em comandos git commit rodam o seu linter ou a sua suíte de testes e bloqueiam o commit se as verificações falharem. Diferentemente dos hooks de formatação, que disparam a cada edição, os hooks de qualidade agem só em momentos específicos, o que mantém o custo baixo.

O ancestral conceitual são os hooks do Git⁸: pre-commit, pre-push e post-commit cumprem esses mesmos três papéis. Os hooks do Claude Code estendem o padrão das operações do Git para cada ação de ferramenta que o agente executa. Disseco essa evolução em every hook is a scar: cada hook existe porque algo deu errado sem ele.

Fundamentos da configuração de hooks

Os hooks vivem nos seus arquivos de configuração:

• No nível do projeto: .claude/settings.json na raiz do repositório (compartilhado com o time)³
• No nível do usuário: ~/.claude/settings.json (seus hooks pessoais, aplicados globalmente)³

A estrutura JSON:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/your/script.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/another-script.sh"
          }
        ]
      }
    ]
  }
}

Cada entrada tem um matcher que filtra nomes de ferramenta como Bash, Write, Edit, Read, Glob, Grep ou Agent, e um array hooks com as definições. A semântica do matcher, segundo a referência: "*", "" ou um matcher omitido correspondem a tudo; um valor formado por letras, dígitos, _, -, |, vírgulas e espaços é um nome exato ou uma lista, então Write|Edit corresponde às duas ferramentas (o sublinhado conta nos nomes de ferramentas MCP, como mcp__github__search_code); qualquer outra coisa é tratada como expressão regular sem âncoras. A correspondência diferencia maiúsculas de minúsculas – bash nunca corresponde a Bash. Cada hook indica um type ("command" para comandos de shell) e o command a executar.

Você pode inspecionar os hooks registrados com o navegador somente leitura /hooks dentro de uma sessão; para adicionar, alterar ou remover hooks, edite o JSON de configuração diretamente.⁵

Quando um hook dispara, o Claude Code entrega o contexto como um objeto JSON no stdin: o nome da ferramenta, a entrada da ferramenta (incluindo file_path nas operações com arquivos) e os metadados da sessão.⁶ Seu script lê o stdin – normalmente com jq – para tomar decisões. Algumas variáveis de ambiente também trazem contexto – $CLAUDE_PROJECT_DIR para resolver caminhos e $CLAUDE_EFFORT para o nível de esforço atual –, mas os campos específicos de cada ferramenta, como o caminho do arquivo, chegam só pelo stdin; não existe nenhuma variável $FILE_PATH por ferramenta.

5 hooks práticos

Cada hook abaixo resolve um problema real que encontrei usando o Claude Code como minha principal ferramenta de desenvolvimento. Todos os exemplos usam o esquema aninhado correto da referência de hooks⁷.

1. Formatação automática ao editar um arquivo

O Claude escreve código funcionalmente correto que, de vez em quando, quebra as regras de formatação do projeto. No começo tentei colocar “sempre rode o black depois de editar arquivos Python” no meu CLAUDE.md, mas a instrução funcionava só em cerca de 80% das vezes. Às vezes o modelo pulava a etapa de formatação quando estava concentrado em uma mudança complexa envolvendo vários arquivos. Um hook PostToolUse elimina essa inconsistência por completo: o seu formatador roda depois de cada escrita de arquivo, independentemente do que o modelo decidiu fazer.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path // empty\"); if [[ \"$FILE\" == *.py ]]; then black --quiet \"$FILE\" 2>/dev/null; elif [[ \"$FILE\" == *.js || \"$FILE\" == *.ts ]]; then npx prettier --write \"$FILE\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

O hook lê a entrada JSON da ferramenta no stdin e extrai .tool_input.file_path com jq – esse objeto do stdin é o único lugar onde o caminho do arquivo existe, já que o Claude Code não define variáveis de ambiente por ferramenta. Em seguida ele confere a extensão e roda o formatador adequado: arquivos Python recebem black, arquivos JavaScript e TypeScript recebem prettier. O 2>/dev/null silencia a saída barulhenta, para que você veja apenas erros de verdade.

Em projetos maiores, mova o comando embutido para um script separado, por legibilidade.

2. Barreira de segurança para comandos perigosos

Hooks PreToolUse na ferramenta Bash inspecionam o comando que o Claude está prestes a rodar e o bloqueiam se ele corresponder a um padrão perigoso. Escrevi a primeira versão desse hook depois que o Claude fez um force-push na main durante uma sessão de refatoração. (Exploro as implicações mais amplas da autonomia dos agentes em anatomy of a claw e Claude Code as infrastructure.) O modelo tinha recebido o pedido de “subir as mudanças” e interpretou isso como git push --force origin main, porque o branch havia divergido. A correção levou segundos; o incidente motivou uma barreira permanente.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"rm\\s+-rf\\s+/|git\\s+push\\s+(-f|--force)\\s+(origin\\s+)?main|git\\s+reset\\s+--hard|DROP\\s+TABLE|:\\(\\)\\s*\\{\\s*:\"; then echo \"BLOCKED: Dangerous command detected: $CMD\" >&2; exit 2; fi'"
          }
        ]
      }
    ]
  }
}

Quando esse hook termina com o código 2, o Claude Code cancela o comando pendente. A mensagem de erro aparece tanto no seu terminal quanto no contexto do Claude, então o modelo entende por que a ação falhou e sugere uma alternativa mais segura.

Padrões bloqueados: - rm -rf / (exclusão recursiva a partir da raiz) - git push --force main e git push -f main (force-push no branch main) - git reset --hard (destruição de trabalho não commitado) - DROP TABLE (destruição acidental do banco de dados) - Fork bombs (o padrão detecta a abertura :(){, o que cobre as variantes com e sem espaço)

Adapte essa lista ao seu ambiente. Bancos de dados de produção pedem padrões de SQL destrutivo. Deploys feitos por CLI pedem guardas para os comandos de deploy.

3. Execução de testes depois das mudanças

Quando o Claude edita um arquivo Python, rode automaticamente os testes correspondentes. Executar os testes na hora pega regressões antes que elas se acumulem ao longo de três ou quatro edições seguintes.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path // empty\"); if [[ \"$FILE\" == *.py && \"$FILE\" != *test_* ]]; then TEST_FILE=\"tests/test_$(basename \"$FILE\")\"; if [[ -f \"$TEST_FILE\" ]]; then if ! OUT=$(python -m pytest \"$TEST_FILE\" -x --tb=short 2>&1); then echo \"TESTS FAILED after editing $FILE:\" >&2; echo \"$OUT\" | tail -20 >&2; exit 2; fi; fi; fi'"
          }
        ]
      }
    ]
  }
}

O hook extrai do JSON do stdin o caminho do arquivo editado, verifica se é um arquivo-fonte Python (e não um arquivo de teste), procura o arquivo de teste correspondente pela convenção de nomes com prefixo test_ e o executa se encontrar. A flag -x para na primeira falha e o tail -20 mantém a saída enxuta. O que torna o hook útil é o exit 2 em caso de falha: um hook PostToolUse não consegue desfazer a edição que já aconteceu, mas o código 2 entrega ao Claude, pelo stderr, a saída dos testes que falharam, e ele corrige a quebra antes de seguir adiante. Uma versão que apenas imprime a falha com código 0 manda tudo para o log de depuração, onde ninguém olha.

Observação: o hook acima pressupõe um diretório tests/ plano com nomes iniciados por test_. Em projetos que espelham a árvore de código-fonte (por exemplo, tests/api/test_users.py correspondendo a src/api/users.py), substitua a linha TEST_FILE por:

TEST_FILE="tests/$(echo "$FILE" | sed 's|.*/src/||; s|\([^/]*\)\.py$|test_\1.py|')"

O hook de execução de testes é especialmente valioso em sessões de refatoração nas quais o Claude mexe em vários arquivos. Sem retorno imediato, os erros se acumulam: o Claude edita o arquivo A, quebra os testes do arquivo B e então edita o arquivo C partindo do estado quebrado de B. Quando você descobre a falha, há três arquivos a consertar em vez de um. Rodar os testes depois de cada edição pega a primeira quebra na hora.

4. Notificação quando o Claude terminar

Turnos longos do Claude Code podem levar minutos. Em vez de ficar olhando para o terminal, receba uma notificação quando o Claude terminar de responder. (Stop dispara ao fim de cada resposta – para um hook no encerramento real da sessão, registre SessionEnd.)

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude finished responding\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

A variante para macOS acima usa osascript para disparar uma notificação nativa. No Linux, troque a linha do osascript por notify-send "Claude Code" "Finished responding". Para notificações no Slack, use um webhook:

curl -s -X POST "$SLACK_WEBHOOK_URL" \
  -H 'Content-type: application/json' \
  -d '{"text": "Claude Code finished responding"}'

Uso a variante do Slack em tarefas de segundo plano iniciadas com & <task> (o modo em segundo plano do Claude Code). A notificação de desktop dá conta das sessões interativas.

5. Verificação de qualidade antes do commit

Antes que o Claude rode git commit, valide que o código passa no linter. Uma barreira de lint antes do commit pega problemas que só a formatação não vê: imports não usados, variáveis indefinidas, erros de tipo.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"^git\\s+commit\"; then if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then echo \"LINT FAILED -- fix before committing:\" >&2; echo \"$LINT_OUTPUT\" >&2; exit 2; fi; fi'"
          }
        ]
      }
    ]
  }
}

A barreira de qualidade só é ativada quando o comando Bash começa com git commit. Ela roda o ruff (um linter Python rápido) com as regras de erro, pyflakes e aviso. Se houver qualquer problema, o hook bloqueia o commit (código 2) e o Claude vê a saída do linter, o que normalmente o leva a corrigir os problemas e tentar de novo.

Você pode empilhar várias verificações de qualidade: mypy para checagem de tipos, bandit para varredura de segurança ou os scripts de validação do seu próprio projeto. Hooks PreToolUse em comandos Bash dão a você uma barreira programável antes de qualquer ação de shell.

PreToolUse e PostToolUse no .claude/settings.json: a referência

Se você procurou o formato da configuração de PreToolUse/PostToolUse e chegou aqui, esta é a versão compacta. Os dois eventos ficam aninhados sob a chave hooks de .claude/settings.json (projeto) ou ~/.claude/settings.json (usuário); os escopos se somam, e handlers idênticos são deduplicados. Um bloco ligando os dois eventos:³

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/guard.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": ".claude/hooks/format.sh" }]
      }
    ]
  }
}

O contrato em três linhas: os dois eventos entregam o JSON da ferramenta no stdin (.tool_input.command para Bash, .tool_input.file_path para Write/Edit – não há variável de ambiente por ferramenta).⁶ PreToolUse dispara antes da chamada da ferramenta e pode bloqueá-la com o código 2. PostToolUse dispara depois que a ferramenta tem sucesso – ele não desfaz a ação, mas o código 2 devolve o stderr ao Claude, que então conserta o que o hook apontou.²

Para a documentação completa dos dois eventos – campos de saída JSON, permissionDecision, updatedInput, tempos limite – a referência oficial é code.claude.com/docs/en/hooks; a seção de hooks do meu guia do Claude Code cobre o mesmo terreno com padrões testados na prática.

Chutou o nome de um evento? O mapeamento

Eventos de hook que as pessoas procuram versus o que o Claude Code realmente dispara:¹

Existem trinta e um eventos no total – a tabela de eventos do guia lista todos eles.

Um hook PreToolUse, PostToolUse e Stop em uma única configuração

Os três eventos mais procurados, ligados juntos – uma guarda de comandos, um formatador e uma notificação de conclusão:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/guard-bash.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "bash -c 'FILE=$(jq -r \".tool_input.file_path // empty\"); [[ \"$FILE\" == *.py ]] && black --quiet \"$FILE\" || true'" }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude finished responding\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

O guard-bash.sh é a barreira de segurança do hook 2 movida para um script separado: salve o corpo do comando de uma linha bash -c do hook 2 (tudo o que está entre as aspas simples externas) como .claude/hooks/guard-bash.sh, acrescente um shebang #!/bin/bash e torne-o executável com chmod +x – ou pegue o script pronto de mesmo nome em Claude Code Hooks Explained. Cada evento mantém a própria semântica: a guarda PreToolUse pode vetar comandos (código 2), o formatador PostToolUse roda depois de cada edição correspondente e o hook Stop dispara ao fim de cada resposta – sem precisar de matcher: Stop não é um evento de ferramenta, então não há nada a filtrar.¹

Dicas para depurar hooks

Hooks falham em silêncio com mais frequência do que se imagina. Cinco técnicas que uso para depurá-los:

1. Teste os scripts isoladamente primeiro. Mande um JSON de exemplo para o script na mão: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh. Se falha fora do Claude Code, também falha dentro dele.
2. Saiba para onde o stderr realmente vai. O stderr chega ao contexto do Claude só quando o hook termina com 2; com o código 0 ele cai no log de depuração, e com outros códigos diferentes de zero aparece apenas um aviso de erro de hook na transcrição. Durante o desenvolvimento, rode claude --debug (ou /debug no meio da sessão) e acompanhe o log de depuração, onde cai a saída dos hooks que terminam com 0.
3. Fique de olho nas falhas do jq. Se o seu caminho JSON estiver errado, o jq⁹ devolve null em silêncio e suas condições nunca vão bater. Teste suas expressões jq contra entradas de ferramenta reais.
4. Confira os códigos de saída. O código 2 bloqueia ações. O código 1 só avisa. Um hook PreToolUse que usa exit 1 por acidente não impõe nada, embora pareça funcionar. Comece permissivo (código 0 por padrão) e use exit 2 apenas para padrões específicos que você quer bloquear.
5. Mantenha os hooks rápidos. Hooks rodam de forma síncrona. Um hook que leva 5 segundos acrescenta 5 segundos a cada uso de ferramenta correspondente. Mantenho todos os meus hooks abaixo de 2 segundos, de preferência abaixo de 500 milissegundos.

O erro mais comum com hooks: escrever uma barreira de segurança com exit 1 em vez de exit 2. O hook parece funcionar durante os testes, porque a mensagem de aviso aparece no terminal. Mas o código 1 é um aviso que não bloqueia. O comando perigoso é executado assim mesmo. Já vi esse erro nas configurações de hooks de três times diferentes, cada um convencido de que tinha bloqueado os force-pushes. Teste todo hook de segurança disparando o padrão bloqueado e conferindo se a ação foi de fato impedida, e não apenas avisada.

Próximos passos

Esses cinco hooks cobrem o básico: formatação, segurança, testes, notificações e barreiras de qualidade. Quando esses padrões ficarem confortáveis, você pode construir hooks para injeção de contexto (adicionar instruções específicas do projeto no início da sessão), guardas de recursão (evitar loops infinitos de subagentes) e orquestração de fluxos de trabalho (encadear processos de várias etapas).

Para a arquitetura dos hooks, o ciclo de vida completo com 31 eventos e padrões avançados, veja a seção de hooks do meu Claude Code guide completo, ou o passeio evento a evento em Claude Code Hooks Explained.

Também escrevi sobre as histórias de origem dos meus 95 hooks de produção em Claude Code Hooks: Why Each of My 95 Hooks Exists, que percorre os incidentes que motivaram cada um deles.

Referências

FAQ

Os hooks podem impedir que o Claude Code rode um comando?

Sim. Hooks PreToolUse bloqueiam qualquer ação de ferramenta terminando com o código 2. O Claude Code cancela a ação pendente e mostra ao modelo a saída de stderr do hook. O código 1 é um erro de hook que não bloqueia: a ação segue adiante. A distinção entre os códigos importa: todo hook de segurança precisa usar exit 2, não exit 1.² O Claude vê o motivo da recusa e sugere uma alternativa mais segura.

Onde eu coloco os arquivos de configuração dos hooks?

As configurações de hooks vão em .claude/settings.json para hooks no nível do projeto (versionados no repositório, compartilhados com o time) ou em ~/.claude/settings.json para hooks no nível do usuário (pessoais, aplicados a todos os projetos). Quando os dois existem, os hooks se somam em vez de se sobrescrever: cada hook correspondente de cada escopo é executado, e handlers idênticos são deduplicados. Recomendo caminhos absolutos para os arquivos de script, para evitar problemas com o diretório de trabalho.

Os hooks funcionam com subagentes?

Sim. Os hooks também disparam nas ações dos subagentes.⁴ Se o Claude iniciar um subagente pela ferramenta Agent, seus hooks PreToolUse e PostToolUse rodam para cada ferramenta que esse subagente usar. Sem aplicação recursiva dos hooks, um subagente poderia driblar suas barreiras de segurança. O evento SubagentStop permite rodar limpeza ou validação quando um subagente conclui a tarefa.⁴

Quantos hooks são hooks demais?

O limite é o desempenho, não a quantidade. Cada hook roda de forma síncrona, então o tempo total de execução se soma a cada chamada de ferramenta correspondente. Rodo 95 hooks distribuídos entre as configurações de usuário e de projeto sem latência perceptível, porque cada hook termina em menos de 200 ms. O limiar que acompanho: se um hook PostToolUse acrescenta mais de 500 ms a cada edição de arquivo, a sessão fica arrastada. Meça seus hooks com time antes de colocá-los para rodar. Dez hooks rápidos rendem mais do que dois lentos.