O que são os hooks do Claude Code? Exemplos e quando usar (2026)

O Claude Code evolui rápido, então a lista de eventos não para de crescer.

O que são hooks no Claude Code?

Hooks no Claude Code são comandos que você define com antecedência e que o Claude Code roda automaticamente em pontos fixos do ciclo de vida de uma sessão. Em vez de "lembrar" o Claude de fazer algo e torcer para que ele não esqueça, um hook transforma esse comportamento em algo determinístico: quando o momento certo chega, ele roda — independentemente de o modelo "estar a fim" ou não.

Se você já usou Git hooks (como um pre-commit que roda um linter antes de cada commit), essa ideia vai soar familiar. A única diferença é que esses hooks se ligam ao ciclo de vida de um agente de código com IA, e não ao Git. Quando o Claude está prestes a rodar uma ferramenta, acabou de editar um arquivo ou encerra um turno de resposta, o Claude Code verifica se há algum hook registrado para aquele evento e o executa.

A maior força de um hook é que ele é determinístico e pode bloquear. Uma linha no seu CLAUDE.md dizendo "lembre de rodar o Prettier depois de editar arquivos" é apenas uma sugestão — o modelo pode esquecer. Já um hook PostToolUse roda o Prettier toda santa vez, sem exceção. Com o PreToolUse, um hook pode até recusar uma ação antes que ela aconteça — por exemplo, bloqueando um rm -rf perigoso.

Isso faz dos hooks a ferramenta central para automatizar o Claude Code: formatar código, rodar testes, registrar atividade, enviar notificações ou construir proteções de segurança. Neste artigo eu mostro como os hooks funcionam via settings.json, três exemplos prontos para copiar e colar, quando você deve (e não deve) usá-los, e uma seção de segurança que a maioria dos guias pula.

Como os hooks funcionam? (settings.json)

Os hooks são declarados no seu arquivo settings.json, sob a chave hooks. A estrutura aninha em três níveis: nome do evento -> lista de matchers -> lista de hooks a rodar. Concretamente, isso é hooks > EventName > [{ matcher, hooks: [{ type, command }] }]. Aqui está um settings.json mínimo que realmente funciona:

{
 "hooks": {
 "PostToolUse": [
 {
 "matcher": "Edit|Write",
 "hooks": [
 {
 "type": "command",
 "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\""
 }
 ]
 }
 ]
 }
}

Leia de dentro para fora: quando o evento PostToolUse dispara, o Claude Code compara o matcher (Edit|Write) com o nome da ferramenta que acabou de rodar; se houver correspondência, ele executa cada command do array hooks.

Três escopos de configuração — isso importa porque decide onde um hook se aplica e se ele vai ser commitado no Git:

Plugins também podem trazer seus próprios hooks pelo arquivo hooks/hooks.json deles.

O campo type aceita cinco tipos: command (roda um comando shell — de longe o mais comum), http (chama uma URL), mcp_tool (chama uma ferramenta em um servidor MCP — veja também o que é o MCP e como usá-lo), prompt e agent. Ao longo deste artigo eu foco no command, porque ele está pronto para copiar e colar e cobre 90% do que você vai precisar. (Acertar a sintaxe dos hooks no settings.json é um pré-requisito — JSON inválido significa que o hook simplesmente nunca roda.)

Os principais tipos de evento (ciclo de vida)

Você não precisa decorar todos eles. Para começar, apenas o punhado abaixo cobre a maioria das situações:

Atualização de 2026 (ganho de informação): muitos guias antigos ainda listam só os quatro eventos clássicos. Na prática, o Claude Code hoje tem mais de 30 eventos de ciclo de vida, adicionando outros como PostToolUseFailure, SubagentStart/SubagentStop, PreCompact/PostCompact, SessionEnd e mais, segundo a documentação oficial da Anthropic (code.claude.com/docs/en/hooks, acessada em 2026-08-09). Mas não se preocupe — como iniciante, você só precisa dos 3 a 4 eventos centrais acima; o resto é para cenários avançados.

O matcher decide a qual ferramenta um hook se aplica. Quatro formas comuns: casar com uma única ferramenta exatamente ("Bash"), casar com várias ferramentas com um pipe ("Edit|Write"), uma regex ("mcp__.*" para pegar toda ferramenta MCP) e vazio ou "*", que casa com tudo. Vamos comparar PreToolUse e PostToolUse nos exemplos a seguir.

Exemplo 1 — PreToolUse: bloquear comandos perigosos

Este é o caso de uso mais impressionante e também a proteção de segurança mais prática. A ideia: antes de o Claude rodar qualquer comando Bash, um hook inspeciona o comando; se ele identifica um padrão perigoso como rm -rf, o hook recusa e nunca deixa o comando rodar.

O PreToolUse tem duas maneiras de bloquear. A maneira "limpa" é imprimir um JSON com um permissionDecision definido como um de três valores: "allow" (roda, pula a etapa de confirmação), "deny" (bloqueia totalmente) ou "ask" (força um prompt). A maneira rápida e direta é usar um código de saída: o script sai com exit 2 para bloquear — e, nesse caso, o que você escreveu no stderr é enviado de volta ao Claude para que ele saiba por que foi bloqueado. A configuração:

{
 "hooks": {
 "PreToolUse": [
 {
 "matcher": "Bash",
 "hooks": [
 {
 "type": "command",
 "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/block-danger.sh"
 }
 ]
 }
 ]
 }
}

E o script .claude/hooks/block-danger.sh:

#!/usr/bin/env bash
# Read the JSON payload from stdin, pull out the command Claude wants to run
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command // empty')

if echo "$command" | grep -Eq 'rm[[:space:]]+-rf|git[[:space:]]+push[[:space:]]+--force'; then
 echo "Blocked: command matches a dangerous pattern ($command)" >&2
 exit 2 # exit 2 = block, stderr is sent back to Claude
fi
exit 0 # exit 0 = allow it to continue

O resultado: quando o Claude tenta rodar rm -rf build/, o hook captura, retorna exit 2, o comando nunca roda e o Claude recebe uma mensagem explicando o porquê. Isso é exatamente o que uma regra no CLAUDE.md não consegue garantir — uma regra é só uma sugestão leve, enquanto um hook é uma proteção rígida. Se você quer apertar as permissões em um nível mais alto, leia mais sobre permissões e configuração segura no Claude Code.

Exemplo 2 — PostToolUse: formatar o código automaticamente

Um dos primeiros hooks que eu ativo em todo projeto: rodar o formatador automaticamente cada vez que o Claude edita um arquivo. Chega de diffs bagunçados por um espaço faltando ou uma quebra de linha errada. Como este é PostToolUse (ele roda depois que a ferramenta tem sucesso), ele não bloqueia nada — só arruma a bagunça.

{
 "hooks": {
 "PostToolUse": [
 {
 "matcher": "Edit|Write",
 "hooks": [
 {
 "type": "command",
 "command": "cd \"${CLAUDE_PROJECT_DIR}\" && npx prettier --write \"$CLAUDE_FILE_PATHS\""
 }
 ]
 }
 ]
 }
}

O matcher Edit|Write pega as duas ferramentas de edição de arquivo. Para um projeto Python, troque o comando por black "$CLAUDE_FILE_PATHS" ou ruff format. Algumas variáveis de ambiente úteis que o Claude Code passa para um hook:

• ${CLAUDE_PROJECT_DIR} — o caminho absoluto para a raiz do projeto, para que o comando rode no diretório certo.
• $CLAUDE_FILE_PATHS — o(s) caminho(s) do(s) arquivo(s) que acabaram de ser mexidos, para que você formate o arquivo certo em vez do repositório inteiro.
• Você também pode sempre ler o payload JSON completo do stdin (como no Exemplo 1) para obter os detalhes de tool_input.

Dica: mantenha o comando leve e rápido. Um hook PostToolUse roda depois de cada edição de arquivo, então um formatador lento vai arrastar a sessão inteira.

Exemplo 3 — Stop: avisar quando o Claude terminar

Quando você passa uma tarefa longa para o Claude e vai fazer outra coisa, é fácil esquecer de voltar para conferir. Um hook Stop roda quando o Claude termina um turno de resposta — perfeito para disparar uma notificação. Aqui está um exemplo usando o ntfy para enviar um push para o seu celular:

{
 "hooks": {
 "Stop": [
 {
 "hooks": [
 {
 "type": "command",
 "command": "curl -s -d \"Claude Code finished the task\" ntfy.sh/your-topic-name"
 }
 ]
 }
 ]
 }
}

Nenhum matcher é necessário porque o Stop não está atrelado a nenhuma ferramenta. No macOS você pode trocar por osascript -e 'display notification "Done!" with title "Claude Code"'; no Linux use notify-send. Pequeno, mas incrivelmente útil quando você está fazendo malabarismo com várias coisas ao mesmo tempo.

Quando você deve — e quando NÃO deve — usar um hook

Hooks são poderosos, mas não são a ferramenta para tudo. A linha é simples: hooks são para coisas que devem sempre rodar e são determinísticas — formatar, testar, bloquear comandos, registrar. Se o que você precisa é orientação de comportamento ou uma capacidade, existe uma ferramenta mais adequada.

Um exemplo fácil de errar: "lembrar o Claude de sempre escrever testes" deveria ser uma regra no CLAUDE.md, não um hook — porque é orientação leve. Mas "rodar a suíte de testes completa depois de editar arquivos em src/" é genuinamente um hook, porque é determinístico. Se esses quatro conceitos ainda parecem embaçados, eu tenho um texto dedicado sobre como skills, subagents, hooks e MCP se diferenciam — é ali que o quadro completo se junta.

⚠️ Notas de segurança ao usar hooks

Esta é a seção que a maioria dos guias pula, e ainda assim é a mais importante. Segundo a documentação oficial (code.claude.com/docs/en/hooks, acessada em 2026-08-09): os hooks rodam com todas as permissões da sua conta de usuário e SEM sandbox. Isso significa que um hook com bug — ou um malicioso que você copiou por acidente — pode apagar arquivos, vazar segredos ou rodar código arbitrário na sua máquina, de forma totalmente automática e sem perguntar.

Alguns princípios que eu sempre sigo:

• Leia cada hook com cuidado antes de habilitá-lo — especialmente hooks que vêm de um plugin, de um kit ou do repositório de outra pessoa. Trate como código rodando como root.
• Nunca deixe segredos hardcoded (tokens, chaves de API) em um comando. Leia-os de variáveis de ambiente em vez de escrevê-los inline.
• Mantenha hooks sensíveis no .claude/settings.local.json (no .gitignore) para não commitá-los sem querer em um repositório compartilhado.
• Conheça o botão de emergência: use disableAllHooks para desligar todos os hooks enquanto depura ou quando algo parece suspeito. Empresas podem travar ainda mais com allowManagedHooksOnly e allowedHttpHookUrls.
• Cuidado com um PreToolUse que faz allow automático — ele pula a etapa de confirmação, o que é conveniente, mas remove uma camada de proteção.

Resumo da ópera: um hook é uma faca afiada. Muito útil, mas você precisa segurá-la do jeito certo. Veja mais problemas comuns e soluções em solução de problemas de erros comuns do Claude Code.

Indo mais rápido: hooks e skills prontos de um kit

Escrever seus próprios hooks, scripts e skills para cada projeto dá um trabalho de verdade — especialmente quando você quer um conjunto consistente de proteções de segurança e fluxos de trabalho. Alguns kits para o Claude Code, como o kit AgentKit para o Claude Code, empacotam skills, subagents e fluxos de trabalho para você não ter que construir tudo do zero. Se você quer ver na prática, pode conferir os preços do AgentKit (20% de desconto pelo link). Deixando claro: os hooks básicos deste artigo você mesma consegue construir e não precisa comprar nada; um kit só vale a pena considerar quando você quer um conjunto inteiro já pronto.

Depuração: por que o meu hook não está rodando?

Um hook "silencioso" é o problema mais comum. Passar por esta checklist quase sempre encontra a causa:

• O JSON é válido? Uma única vírgula sobrando no settings.json e o arquivo inteiro deixa de carregar. Passe por um validador de JSON.
• O matcher usa o nome de ferramenta correto? Os nomes diferenciam maiúsculas de minúsculas: é Bash, Edit, Write — e não bash ou edit.
• O script retorna o código de saída certo? exit 0 para passar, exit 2 para bloquear (com PreToolUse). Outros códigos de saída podem ser ignorados.
• O stdout está "limpo"? Se o hook retorna JSON de controle, o stdout deve conter apenas esse JSON — texto solto quebra a análise.
• O script é executável? No macOS/Linux, lembre do chmod +x.
• O disableAllHooks está ligado? Se você desligou os hooks antes para depurar, não esqueça de ligá-los de volta.

Perguntas frequentes (FAQ)

Qual a diferença entre um hook, um slash command e uma skill?

Um hook roda automaticamente em pontos do ciclo de vida (você não o chama à mão). Um slash command é uma ação que você mesma dispara quando precisa. Uma skill é uma capacidade empacotada (instruções + scripts) que o Claude carrega sozinho quando o contexto encaixa. Em resumo: hook = automático e determinístico, slash command = manual, skill = uma capacidade reutilizável.

Os hooks funcionam no Windows?

Sim. Como type: command roda um comando shell, você pode apontá-lo para um script PowerShell (powershell -File .claude\hooks\block-danger.ps1) ou usar o Git Bash/WSL para rodar um script bash. O comando só precisa ser válido no shell da sua máquina.

Os hooks deixam o Claude Code mais lento?

Podem, se o comando for pesado. Os hooks rodam de forma síncrona no momento do evento, então um formatador ou uma suíte de testes lentos vão esticar cada turno. Mantenha os hooks leves, formate só o arquivo que acabou de mudar ($CLAUDE_FILE_PATHS) em vez do repositório inteiro, e considere tirar os testes pesados do PostToolUse.

Qual a diferença entre hooks globais e de projeto?

Um hook global (~/.claude/settings.json) se aplica a todo projeto na sua máquina e não é commitado. Um hook de projeto (.claude/settings.json) se aplica só àquele projeto e pode ser commitado para o time inteiro compartilhar. A variante .local.json é por projeto, mas fica no .gitignore, para a sua própria configuração privada.

Dá para bloquear comandos perigosos com um hook?

Sim, e é exatamente aí que está a força do PreToolUse. O hook inspeciona o comando antes de ele rodar e o recusa com permissionDecision: "deny" ou código de saída 2 — por exemplo, bloqueando rm -rf ou git push --force (veja o Exemplo 1 acima).

Os hooks são seguros?

Os hooks rodam com todas as suas permissões de usuário e sem sandbox, então um hook com bug ou malicioso pode causar dano de verdade (apagar arquivos, vazar segredos). O mecanismo em si é seguro se você escreve e revisa seus hooks com cuidado; o risco vem de habilitar um hook desconhecido sem lê-lo. Sempre trate um hook como código rodando com os privilégios mais altos.

Conclusão + próximos passos

Domine os três eventos centrais e você pode usar hooks para quase tudo o que precisa: PreToolUse para bloquear comandos perigosos, PostToolUse para formatar/testar automaticamente e Stop para ser avisada. Lembre da regra de ouro: os hooks rodam com permissões totais e sem sandbox — revise-os com cuidado antes de habilitar. Para ir além, leia o que são skills no Claude Code e slash commands no Claude Code, ou dê um passo atrás para ver o quadro geral sobre como skills, subagents, hooks e MCP se diferenciam e quando usar cada um.