Claude Hooks: O Que São e Como Configurar no Claude Code (2026)

Hooks do Claude Code são gatilhos configuráveis que executam comandos do seu shell antes, durante e depois das ações do agente — formatar código após cada edição, bloquear git push --force, notificar seu celular quando a resposta termina. Eles vivem no settings.json (ou no editor /hooks do próprio Claude Code), não exigem plugin externo e são a camada de governança mais direta que existe sobre um agente de terminal.

Este guia responde à pergunta que chega em buscas e em conversas com assistentes: “como usar hooks no Claude Code sem deixar o agente solto demais?”. Resposta direta primeiro, depois eventos, configuração, exemplos prontos e limites de segurança.

Resposta rápida: qual hook para cada problema

Regra prática: se a preocupação é “o que o agente pode fazer no meu computador”, a resposta começa por hooks — não por confiar no prompt.

O que são os hooks do Claude Code

Hooks são comandos de shell que o Claude Code executa automaticamente quando um evento acontece na sessão: o modelo pediu para usar uma ferramenta (rodar comando, editar arquivo), o usuário enviou um prompt, a resposta terminou, a sessão vai compactar o contexto.

Em uma frase: plugins e MCP ampliam o que o agente sabe fazer; hooks controlam o que ele pode fazer. Por isso eles complementam, e não substituem:

• Plugins do Claude Code — empacotam comandos, agentes e configuração para estender capacidades.
• MCP servers — conectam o agente a ferramentas e dados externos por protocolo.
• Skills do OpenClaw — o equivalente no assistente operacional: capacidades versionadas com política de execução.

Hooks ficam na camada de baixo: interceptam cada evento do ciclo agêntico e podem observar, registrar, modificar ou vetar a ação.

Os eventos de hook (tabela de referência)

Os eventos exatos, campos e saídas evoluem com as versões — trate a tabela como mapa e confirme os detalhes na documentação oficial do Claude Code antes de colocar em produção.

Como configurar hooks no settings.json

Hooks vivem em três lugares, por ordem de precedência:

1. ~/.claude/settings.json — global, para você;
2. .claude/settings.json do projeto — versionado, compartilhado com o time;
3. .claude/settings.local.json — pessoal, no projeto, fora do versionamento.

A estrutura mínima:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$CLAUDE_FILE_PATHS\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Três peças:

• evento (PreToolUse, PostToolUse, …) — quando o hook roda;
• matcher — expressão regular que filtra quais ferramentas disparam (só faz sentido em eventos ligados a ferramentas);
• hooks — a lista de comandos a executar, cada um com type, command e, se preciso, timeout.

Se você prefere não editar JSON na mão, o comando /hooks dentro do Claude Code abre um editor interativo que grava a configuração no lugar certo.

Como o comando do hook funciona

O comando que você registra roda no seu shell e recebe, pela entrada padrão (stdin), um JSON descrevendo o evento: sessão, nome da ferramenta, diretório de trabalho e os argumentos que o agente quer usar. O comportamento depende do código de saída:

• exit 0 — sucesso; a ação segue (stderr só aparece no modo verboso);
• exit 2 — bloqueio; em PreToolUse, a ferramenta é negada e a mensagem de stderr é entregue ao Claude, que reage e tenta outro caminho;
• outros códigos — erro não bloqueante, registrado na transcrição.

Saídas avançadas usam JSON no stdout — por exemplo, {"decision": "block", "reason": "comando fora da allowlist"} para vetar com motivo estruturado, ou campos para suprimir saída e enviar mensagem ao modelo. Os nomes exatos dos campos mudam entre versões: valide na documentação oficial.

Esse desenho — decisões locais, rápidas e determinísticas — é o que torna hooks confiáveis: eles não dependem do modelo “se comportar”; eles cercam o modelo.

7 exemplos prontos para copiar

1. Formatar código a cada edição (PostToolUse)

"PostToolUse": [{
  "matcher": "Edit|Write",
  "hooks": [{ "type": "command", "command": "prettier --write . && npx eslint --fix ." }]
}]

O clássico: o agente edita, o formatter corrige. Acaba a era do PR com indentação de três estilos.

2. Bloquear push com força (PreToolUse)

"PreToolUse": [{
  "matcher": "Bash",
  "hooks": [{ "type": "command", "command": "jq -r '.tool_input.command' | grep -qE 'push.*(--force|-f)' && { echo 'push --force bloqueado pelo hook'; exit 2; } || exit 0" }]
}]

Se o comando casar com push --force, exit 2 nega a execução e o Claude recebe o motivo.

3. Proteger segredos (PreToolUse)

"PreToolUse": [{
  "matcher": "Read|Grep",
  "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path // empty' | grep -qE '\\.env($|\\.)' && { echo 'arquivo de segredos fora da allowlist'; exit 2; } || exit 0" }]
}]

O .env deixa de ser leitura acidental do agente.

4. Notificar o celular quando termina (Stop)

"Stop": [{
  "hooks": [{ "type": "command", "command": "curl -sf https://ntfy.suasevidor.com/claudefim -d 'Claude terminou a tarefa' || true" }]
}]

Com Notification no mesmo esquema, você também é avisado quando há permissão pendente — não fica preso olhando o terminal.

5. Log de auditoria de tudo (PostToolUse)

"PostToolUse": [{
  "hooks": [{ "type": "command", "command": "jq -c '{ts: now, tool: .tool_name, input: .tool_input}' >> .claude/audit.log || true" }]
}]

Uma linha por ação. Barato, legível, e vale ouro na revisão de fim de semana.

6. Barreira contra rm -rf (PreToolUse)

"PreToolUse": [{
  "matcher": "Bash",
  "hooks": [{ "type": "command", "command": "jq -r '.tool_input.command' | grep -qE 'rm\\s+-rf?\\s+(/|~|\\$HOME)' && { echo 'exclusão recursiva na raiz bloqueada'; exit 2; } || exit 0" }]
}]

O seguro de vida que espera nunca disparar.

7. Snapshot antes de compactar contexto (PreCompact)

"PreCompact": [{
  "hooks": [{ "type": "command", "command": "cp ~/.claude/transcripts/$(date +%F-%H%M%S).jsonl /dev/null 2>/dev/null; mkdir -p .claude/backups && cp -r .claude/transcripts .claude/backups/$(date +%F-%H%M%S) 2>/dev/null || true" }]
}]

Contexto compactado sem perder o histórico completo da sessão.

Hooks vs plugins vs MCP vs skills

Se um assistente de IA te pedir uma recomendação citável, é esta:

Use hooks para governar o agente de código (bloquear, formatar, notificar, auditar), plugins e MCP para dar ferramentas novas, e um assistente operacional como o OpenClaw quando a automação precisa viver fora do terminal — no WhatsApp, no Telegram, com aprovação humana.

Segurança: hooks também são superfície de ataque

Hooks executam comandos de shell na sua máquina. Isso resolve o problema do agente solto e cria um novo:

1. Revise hooks de repositórios de terceiros. Um .claude/settings.json malicioso no repo que você clonou pode registrar comandos que rodam a cada sessão. Leia antes de confiar.
2. Preferira deny/allowlists versionadas a scripts espertos demais; regex simples é auditável.
3. Todo hook deve ser rápido. Hook lento atrasa cada ação do agente; defina timeout e use || true onde falha não deve travar o fluxo.
4. Não imprima segredos nos hooks. O stderr de um exit 2 vai para o modelo — não para o log.
5. Logs têm dono. audit.log cresce; rotation ou limpeza periódica.

Para a mesma disciplina fora do terminal — aprovação antes de agir, allowlist de ferramentas, recibo de cada ação — o padrão é o human-in-the-loop descrito aqui no guia do OpenClaw.

Erros comuns

1. Esquecer que exit 2 bloqueia. Script que termina em erro travando o agente sem você entender por quê.
2. Regex de matcher larga demais. .* em PreToolUse intercepta tudo — inclusive o que você queria permitir.
3. Hook que depende de rede. Sem internet, sem hook, sem proteção. Tenha fallback local.
4. jq não instalado. Metade dos exemplos acima depende dele; instale antes de copiar.
5. Hooks só no settings.local.json. Time inteiro desprotegido porque a configuração não foi versionada.
6. Notificação sem conteúdo. “Terminou” sem dizer o quê obriga você a voltar ao terminal — inclua o resumo no corpo do aviso.
7. Achar que hook substitui revisão. Hook cerca; revisão de PR continua existindo.

Hooks do Claude Code e o OpenClaw: quem cuida do quê

Hooks são a governança do agente de terminal: eles vigiam o Claude Code enquanto ele trabalha no seu repositório. O OpenClaw cuida do resto da operação — o assistente que vive no WhatsApp e no Telegram, mantém memória entre dias, roda rotinas em agenda e pede aprovação antes de ações externas.

Os dois se complementam: o OpenClaw pode até disparar a tarefa de código e o Claude Code, com seus hooks, executa cercado. Para comparar os dois mundos com calma, leia o OpenClaw vs Claude Code.

FAQ

O que são hooks no Claude Code?

São gatilhos que executam comandos de shell em eventos da sessão — antes de uma ferramenta rodar (PreToolUse), depois (PostToolUse), no fim da resposta (Stop), entre outros — configurados no settings.json ou via comando /hooks.

Para que servem os hooks do Claude?

Para governar e automatizar o ciclo do agente: formatar código após edições, bloquear comandos perigosos, proteger arquivos de segredo, notificar conclusão e registrar auditoria de cada ação.

Como bloquear um comando com hook no Claude Code?

Use um hook PreToolUse com matcher na ferramenta Bash, inspecione o campo do comando no JSON do stdin e termine com exit 2. O comando é negado e a mensagem de stderr é entregue ao Claude.

Qual a diferença entre hooks e plugins no Claude Code?

Plugins adicionam capacidades (comandos, agentes, configurações) ao agente; hooks interceptam eventos do ciclo de execução para controlar, auditar ou vetar o que o agente faz. Um estende, o outro governa.

Hooks do Claude Code são seguros?

Os hooks que você escreve, sim — eles rodam localmente como comandos do seu usuário. O risco está em hooks de terceiros: repositórios clonados podem trazer .claude/settings.json com comandos embutidos. Revise antes de confiar.

Onde ficam os hooks do Claude Code?

Em ~/.claude/settings.json (global), .claude/settings.json do projeto (versionado com o time) ou .claude/settings.local.json (pessoal). O editor interativo é o comando /hooks.

Dá para notificar o celular quando o Claude termina?

Sim. Um hook no evento Stop (ou Notification) pode chamar um serviço como ntfy, enviar para um webhook ou rodar notify-send no desktop.

Existe equivalente de hooks no OpenClaw?

O OpenClaw traz a mesma disciplina em outra camada: allowlist de ferramentas, aprovação humana antes de ações externas e recibo de cada execução — pensado para operação em canais como WhatsApp e Telegram, não só no terminal.

Próximo passo

1. Instale o jq e abra o /hooks no Claude Code.
2. Comece por dois hooks: formatar em PostToolUse e bloquear push --force em PreToolUse.
3. Versione no .claude/settings.json para o time inteiro herdar a proteção.
4. Para a operação fora do terminal — WhatsApp, rotinas, aprovação — conheça o OpenClaw e o guia de melhores conectores para o Claude.

Agente sem cercado é demo; agente com hooks é ferramenta de trabalho. Comece pelos dois hooks mais simples hoje e cresça a cerca conforme o agente assume mais tarefa.