Hooks do Claude Code explicados: cada evento e para que serve

01Como um hook é estruturado

A configuração de um hook tem três níveis:

1. O evento do hook, como PreToolUse ou Stop.
2. Um grupo de matcher, que filtra quando ele dispara, como "só para a ferramenta Bash".
3. Um ou mais handlers do hook, que é o que de fato executa.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

Isto roda um script de lint depois que o Claude cria ou edita um arquivo. Para adicionar um segundo evento, inclua uma chave irmã dentro do mesmo objeto hooks.

02Onde ficam os hooks

Hooks de arquivos diferentes se somam, em vez de se substituírem. Digite /hooks no Claude Code para ver todos os hooks ativos e de onde cada um veio.

Em uma sessão interativa, o Claude Code segura os hooks, inclusive os seus, até você aceitar o diálogo de confiança do workspace para a pasta.

03Tipos de handler

A maioria dos hooks é "type": "command", que executa um comando de shell. Existem outros quatro:

• http: envia o JSON do evento via POST para uma URL e lê o corpo da resposta.
• mcp_tool: chama uma ferramenta em um servidor MCP que você configurou.
• prompt: faz uma pergunta de turno único a um modelo Claude e lê uma decisão em JSON.
• agent: inicia um subagente que pode ler arquivos antes de decidir (experimental).

Hooks de comando rodam com todas as suas permissões de usuário, via sh -c no macOS e no Linux e via Git Bash (ou PowerShell) no Windows. Adicione "async": true para rodar um hook em segundo plano; nesse caso, ele não pode mais tomar decisões.

04Matchers

O matcher define quais ocorrências de um evento executam o hook. Com o que ele é comparado depende do evento: o nome da ferramenta em eventos de ferramenta, o tipo de notificação em Notification, como a sessão começou em SessionStart, e assim por diante.

• "*", "" ou nenhum matcher corresponde a tudo.
• Letras, dígitos, _, -, espaços, | e , são tratados como nomes exatos. Edit|Write corresponde a qualquer uma das duas ferramentas.
• Qualquer outra coisa é uma expressão regular JavaScript, então mcp__memory__.* corresponde a todas as ferramentas de um servidor MCP.

Matchers diferenciam maiúsculas de minúsculas. Alguns eventos, como Stop e UserPromptSubmit, ignoram matchers. Em eventos de ferramenta, um campo if com uma regra de permissão como "Bash(git *)" restringe ainda mais um handler específico.

05Entrada: o que seu hook recebe

Todo hook recebe um JSON via stdin com alguns campos comuns, incluindo session_id, transcript_path, cwd e hook_event_name, além de campos específicos do evento. Um hook PreToolUse para uma chamada Bash, por exemplo, também recebe tool_name e tool_input.command. Leia com jq ou qualquer parser de JSON:

#!/bin/bash
input=$(cat)
cmd=$(jq -r '.tool_input.command // empty' <<<"$input")
echo "Claude wants to run: $cmd" >> ~/claude-commands.log
exit 0

06Saída: códigos de saída e JSON

Um hook pode responder de duas formas.

Exit codes. 0 significa sucesso. 2 é um erro bloqueante: em eventos que podem bloquear, a ação é interrompida e o seu stderr vira o motivo. Qualquer outro código, incluindo o comum 1, é um erro não bloqueante, então a ação segue normalmente e você vê um aviso de erro do hook. Se o hook serve para impor uma regra, saia com 2, não com 1.

JSON no stdout. Saia com 0 e imprima um único objeto JSON para ter um controle mais fino. Alguns campos funcionam em qualquer evento, como continue: false para parar o Claude por completo. Outros são específicos de cada evento: Stop usa decision: "block" com um reason, enquanto PreToolUse e PermissionRequest colocam a decisão dentro de hookSpecificOutput. Não imprima mais nada no stdout: uma linha perdida do seu perfil de shell impede o Claude Code de ler o JSON.

07Todos os eventos de hook

A Anthropic adiciona eventos de vez em quando, então consulte a referência de hooks para ver a lista atual e os campos de entrada de cada evento.

08Quais eventos importam para notificações

Quatro eventos cobrem quase tudo que as pessoas querem ser avisadas:

• Stop para "o Claude terminou". Veja o guia do Stop hook.
• Notification para "o Claude está esperando por você", com tipos como permission_prompt e idle_prompt. Veja o guia do Notification hook.
• PermissionRequest para ser avisado, ou responder, no instante em que uma permissão for necessária. Veja o guia do PermissionRequest.
• PreToolUse na ferramenta AskUserQuestion, para ver ou responder às perguntas de múltipla escolha do Claude. Veja como responder perguntas pelo celular.

Para uma configuração de desktop pronta para colar, comece por como receber uma notificação quando o Claude Code terminar.

09Onde o Claude Code Notifier se encaixa

O Claude Code Notifier é construído inteiramente sobre esses hooks. Sua ferramenta de linha de comando gratuita, ccn, roda no Mac, Windows e Linux. A instalação adiciona sete entradas de hook ao ~/.claude/settings.json, cada uma executando ccn hook, e faz um backup único do arquivo. O ccn roda por alguns milissegundos a cada evento e depois encerra, então nada fica rodando em segundo plano.

Sozinho, ele mostra notificações no desktop. Com o app de iPhone ou Android pareado, os mesmos hooks levam suas respostas de volta: permitir ou negar uma permissão, responder uma pergunta ou enviar a próxima instrução depois que o Claude para. Ele é independente e não é feito pela Anthropic. Se você só precisa de um log ou de uma etapa de lint, algumas linhas suas são mais simples. Detalhes na página do ccn.

10Perguntas frequentes