Aula 15Hooks: ações automáticas

Objetivos

Ao final desta aula você vai saber:

• O que é uma ação automática (hook) e em que momentos ela roda
• As três camadas: o que o CLAUDE.md pede, o que as regras deny e ask travam e o que a ação automática faz sempre
• Por que o modo Manual e as suas regras já protegem o essencial
• O cuidado antes de aceitar uma ação automática de outra pessoa
• Ver as ações automáticas da sua pasta sem mudar nada, e como desligar todas

Nas Aulas 11 a 14, você deu ao Claude as regras da casa, ajudantes, receitas e conectores. Tudo isso o Claude costuma seguir. Nesta aula, você conhece o que roda sempre: as ações automáticas, que o Claude Code chama de hooks (ganchos).

A aula é curta e só de olhar. Ela usa a pasta da sua página, com o CLAUDE.md da Aula 11 e as regras deny e ask das Aulas 05 e 10. Você não instala nada e não precisa do GitHub.

O que é uma ação automática

Uma ação automática é um comando que roda sozinho, num momento certo, toda vez. Quem a dispara é o programa, o Claude Code, e não o Claude: por isso ela não depende de ele lembrar. Ela fica guardada num arquivo de configurações, como o .claude/settings.json, o mesmo das suas regras deny e ask.

Os momentos mais usados:

Escrever uma ação automática é coisa de quem programa: ela roda um comando, muitas vezes um pequeno programa. Por isso, o passo a passo fica em Para ir além, no fim da aula.

As três camadas

Você já conhece duas maneiras de orientar o Claude. A ação automática é a terceira:

💡 Para quem está começando, isso já basta. O modo Manual e as suas regras deny e ask protegem o essencial: o Claude pede licença antes de mudar um arquivo e antes dos comandos que mudam alguma coisa, e o .env fica trancado. A ação automática serve para quem quer que algo aconteça sempre, sem pedir. O curso não precisa de nenhuma.

💡 Quer um aviso quando o Claude terminar? Isso não precisa de ação automática. Quando o Claude termina uma tarefa ou para num pedido de licença e você parece longe, o Claude Code avisa sozinho. Por padrão, a notificação na tela aparece só nos programas de terminal iTerm2, Ghostty e Kitty. Nos outros, peça ao Claude: "troque o aviso de tarefa terminada pelo bipe do terminal". Ou mude você mesmo: digite /config e procure Local notifications (avisos locais).

O cuidado antes de aceitar uma ação automática

Uma ação automática roda comandos no seu computador, com as suas permissões: ela pode mexer em tudo o que você mexe. E ela não precisa ser sua. Pode vir pronta dentro da pasta de outra pessoa, no .claude/settings.json dela, junto com uma página que alguém mandou.

As ações automáticas de uma pasta só rodam depois que você confia nela, naquela pergunta que o Claude Code faz na primeira vez em que você o abre numa pasta (Aula 03). E a confiança numa pasta costuma valer também para as pastas que estão dentro dela. Por isso, confie só na pasta de cada projeto, nunca numa pasta grande, como a Documentos.

Então:

• Nunca cole uma ação automática enviada por quem você não conhece, nem uma que você não entende.
• Antes de confiar na pasta de outra pessoa, abra o Claude Code na sua pasta de sempre e peça para ele ler o .claude/settings.json da outra pasta e explicar, em português simples, o que cada ação automática faz, sem rodar nada.
• Para desligar todas, peça ao Claude: "desligue todas as ações automáticas nas minhas configurações pessoais". O nome dessa configuração fica em Para ir além.

🛡️ Antes de aprovar algo que roda código no seu computador (uma ação automática, um mod, um plugin, um conector que roda no computador): instale só o que vem de quem você confia, peça ao Claude para explicar em português simples o que aquilo faz e desligue o que não usa.

O exercício: só olhar

Abra o Claude Code na pasta da sua página, no Manual, e peça:

"liste as ações automáticas e as regras deste projeto, em português simples, sem mudar nada"

O critério de pronto: a resposta diz que não há nenhuma ação automática e mostra as regras que você criou, a deny do .env (Aula 05) e a ask do envio para o GitHub (Aula 10). Se aparecer uma ação automática que você não conhece, pergunte ao Claude de onde ela veio antes de seguir.

Para conferir com os próprios olhos, digite /hooks. Ele abre uma lista só para leitura, com cada ação automática configurada e de onde ela vem (as suas configurações pessoais, as do projeto, um plugin). Na sua pasta, não deve aparecer nenhuma. O /hooks não cria nem muda nada, e Esc fecha a lista.

Opcional: uma regra ask para apagar arquivos, pedida como a do envio, na Aula 10:

"crie uma regra ask no .claude/settings.json para que você sempre me pergunte antes de apagar um arquivo"

No Manual, o Claude já pede licença antes de apagar. A regra garante a pergunta também nos outros modos, até no auto. Antes de aprovar a mudança, peça ao Claude para explicar a regra em português simples. Depois, guarde uma versão: "guarde uma versão com uma mensagem em português explicando o que mudou".

Para ir além (opcional): escrever uma ação automática

🔧 Para ir além (para quem já programa; pode pular): esta parte mostra como uma ação automática é escrita por dentro: os eventos, o filtro de ferramentas, o script, os códigos de saída, o jq, o chmod, o formatador e o bloqueio antes do comando. Daqui em diante, ela usa o nome técnico, hook. Se você nunca programou, pule direto para o Na prática.

Por que usar hooks

Hooks permitem rodar comandos em pontos específicos do ciclo de vida do Claude Code. A grande diferença entre hooks e tudo o mais que vimos neste curso é que hooks são determinísticos: eles sempre rodam.

Você pode escrever no seu CLAUDE.md para o Claude rodar o Prettier depois de cada edição. Na maioria das vezes, ele vai rodar. Mas às vezes, não. Um hook faz isso acontecer todas as vezes, sem exceção.

Usos comuns:

• Formatar automaticamente depois de editar arquivos
• Registrar todos os comandos executados, para auditoria e conformidade
• Bloquear operações perigosas, como modificar arquivos de produção
• Levar o aviso de tarefa terminada para outro lugar, como um som seu ou um canal do time. O aviso comum já existe sem hook (veja o 💡 do começo da aula), e um hook de Notification roda junto com ele

Como funcionam

Hooks ficam configurados no settings.json. Você escolhe um evento, opcionalmente define um matcher (para quais ferramentas o hook vale) e informa um comando para rodar.

Os eventos mais comuns:

Esses são só alguns: o Claude Code suporta muitos outros. Veja a lista completa na referência de hooks.

Para criar ou mudar um hook, edite o settings.json ou peça ao Claude: descreva o que você quer ("crie um hook que formate os arquivos TypeScript depois de cada edição") e ele escreve a configuração. O comando /update-config faz o mesmo, especializado em mudar configurações. Edições diretas nos arquivos de settings costumam valer sem reiniciar nada: o Claude Code percebe a mudança sozinho.

O comando /hooks serve para conferir: ele abre uma lista só para leitura dos hooks configurados, com a origem de cada um (as configurações do usuário, as do projeto, as locais, um plugin ou a sessão atual). Escolha um hook para ver o texto completo do que ele roda e onde ele está definido. Para ver todos os eventos, até os que não têm hook, escolha All events, no fim da lista. Ele não cria nem edita hooks.

Exemplo prático: formatação automática

O hook mais comum. Configure um PostToolUse com o matcher "Edit|Write", para que ele dispare sempre que o Claude modificar um arquivo com as ferramentas de edição. O comando verifica a extensão do arquivo e roda o formatador adequado: Prettier para TypeScript, gofmt para Go, o que o seu projeto usar.

.claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/formatar.sh"
          }
        ]
      }
    ]
  }
}

.claude/hooks/formatar.sh:

#!/bin/bash
# O hook recebe um JSON no stdin com os dados da ferramenta
arquivo=$(jq -r '.tool_input.file_path')

case "$arquivo" in
  *.ts|*.tsx|*.js|*.jsx) npx prettier --write "$arquivo" ;;
  *.go)                  gofmt -w "$arquivo" ;;
esac
exit 0

Dois cuidados antes de testar:

• Torne o script executável: chmod +x .claude/hooks/formatar.sh. Os exemplos também usam o jq para ler o JSON; instale-o se ainda não tiver. No Windows, um script de bash precisa do Git Bash (o Git para Windows): sem ele, o comando roda no PowerShell, e um script escrito para o bash pode não funcionar.
• Comandos de shell escapam do matcher. O Edit|Write só pega as edições feitas pelas ferramentas de edição. Se o Claude mudar um arquivo com um comando (um sed, um gerador de código), o hook não dispara. Para cobrir tudo, use também um hook Stop, que confere a pasta uma vez no fim de cada resposta. Para um arquivo específico, mudado por qualquer caminho, use um hook FileChanged: ele vigia o arquivo no disco, e o matcher dele é a lista dos nomes exatos, separados por |, como "index.html|estilo.css".

Bloqueando com PreToolUse

Hooks PreToolUse podem bloquear chamadas de ferramenta antes de elas acontecerem. Seu hook recebe o nome da ferramenta e a entrada dela como JSON no stdin. O código de saída define o comportamento:

⚠️ Por padrão, hooks falham "abertos". Se o script não existir, não for executável (o shell devolve o código 127) ou terminar com exit 1, o Claude Code mostra um aviso e segue com a ação. Só o exit 2 bloqueia. Num hook de bloqueio, acrescente "onFailure": "block" ao lado do "command" (desde a versão 2.1.295): aí um script que falha, estoura o tempo ou some bloqueia a ação em vez de liberá-la. E exit 0 não é uma aprovação: a ação continua passando pelas regras de permissão normais. Teste seu hook de bloqueio antes de confiar nele.

É assim que você garante regras rígidas. Bloquear escrita na pasta de configuração de produção. Bloquear comandos bash com rm -rf. Bloquear commits na main. O que o seu time precisa que seja garantido, e não apenas sugerido.

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

.claude/hooks/bloquear-rm.sh:

#!/bin/bash
comando=$(jq -r '.tool_input.command')

if echo "$comando" | grep -q 'rm -rf'; then
  echo "Bloqueado: 'rm -rf' não é permitido neste projeto. Apague arquivos específicos." >&2
  exit 2
fi
exit 0

Compartilhando hooks com o time

Hooks configurados em .claude/settings.json são de nível de projeto e podem ser commitados no repositório. Assim, o time inteiro recebe os mesmos hooks automaticamente.

Use a variável de ambiente CLAUDE_PROJECT_DIR nos comandos para referenciar scripts guardados no projeto. Assim eles funcionam independentemente da pasta em que o Claude estiver no momento.

Hooks pessoais, em ~/.claude/settings.json, valem só no seu computador: as sessões na nuvem não leem o seu ~/.claude/settings.json. Numa sessão na nuvem com um repositório só, os hooks do .claude/settings.json do repositório valem, porque vêm junto na cópia. Já as conversas de um Projeto (Aula 17) que rodam na nuvem carregam do repositório só o CLAUDE.md e as regras de .claude/rules/, sem os hooks.

A confiança na pasta e o claude -p

Numa sessão interativa, o Claude Code segura os hooks de todos os arquivos de settings, inclusive o seu ~/.claude/settings.json, até você aceitar a pergunta de confiança da pasta (ou de uma pasta de cima cuja confiança vale para ela). Fora de um repositório Git, a confiança vale para as subpastas, menos as que são repositórios; num repositório, vale para o repositório inteiro.

Num claude -p ou numa sessão do Agent SDK, a pergunta nunca aparece e a pasta conta como confiada: os hooks commitados no .claude/settings.json de um repositório rodam mesmo numa pasta em que você nunca confiou. Antes de rodar um claude -p num repositório que não é seu, leia os arquivos de .claude/, comece com --bare ou desligue os hooks daquela execução com --settings '{"disableAllHooks": true}'.

Desligando hooks

Para tirar um hook, apague a entrada dele no arquivo de settings. Não há como desligar um hook só e manter a configuração dele.

Para desligar todos sem apagar, use "disableAllHooks": true (é o que o Claude grava em ~/.claude/settings.json quando você pede para desligar todas as ações automáticas nas suas configurações pessoais). Três detalhes:

• Ele desliga também a status line personalizada e os mods que você instalou (Aula 18). Os mods que vêm com o Claude Code e o que a sua empresa gerencia continuam. Com ele ligado, o /hooks mostra um aviso no lugar dos hooks, e o /goal não roda.
• Vale o valor que sobra depois da precedência das configurações: um "disableAllHooks": false no .claude/settings.json de um projeto vence o true das suas configurações pessoais.
• Para desligar os hooks de uma execução só, seja o que for que o projeto diga, abra com claude --settings '{"disableAllHooks": true}'.

Para testar

1. Peça ao Claude (ou escreva você mesmo no .claude/settings.json) um hook PostToolUse com matcher Edit|Write que rode o formatador do seu projeto. Rode /hooks e confira que ele aparece na lista.
2. Peça ao Claude uma pequena edição e confira que o arquivo saiu formatado.
3. Crie um hook PreToolUse que bloqueie rm -rf com exit 2 (lembre do chmod +x). Peça ao Claude para "limpar a pasta build com rm -rf" e veja como ele reage ao bloqueio.
4. Commite .claude/settings.json e a pasta .claude/hooks/.

Se algo precisa acontecer toda vez, sem falhar, não coloque em um prompt. Coloque em um hook.

Documentação oficial: Hooks e o guia de hooks (em inglês).

Na prática

Use a pasta da sua página (a confeitaria, ou a da sua ideia).

1. Abra o terminal, entre na pasta e abra o Claude Code: cd Documents/confeitaria, com o nome da sua pasta, e depois claude. Aperte Shift + Tab uma vez e confira se aparece manual mode on.
2. Peça: "liste as ações automáticas e as regras deste projeto, em português simples, sem mudar nada". Confira: nenhuma ação automática, a deny do .env e a ask do envio para o GitHub.
3. Digite /hooks e veja a lista, só para leitura. Na sua pasta, não deve aparecer nenhuma ação automática. Aperte Esc para fechar.
4. Saiba onde fica o interruptor, sem mexer nele. Peça: "se um dia eu precisar, como desligo todas as ações automáticas nas minhas configurações pessoais? Só explique, sem mudar nada".
5. (Opcional) Peça a regra ask para apagar arquivos, peça a explicação dela antes de aprovar e guarde uma versão.

Resumo

• Uma ação automática (hook) é um comando que roda sozinho num momento certo, sempre, sem depender de o Claude lembrar.
• São três camadas: o CLAUDE.md pede, as regras deny e ask travam uma ação, e a ação automática roda um comando seu.
• Para quem está começando, o Manual e as regras já protegem o essencial, e o aviso de tarefa terminada não precisa de ação automática.
• Ela roda com as suas permissões: só de quem você confia, e com a explicação do Claude antes de confiar na pasta de outra pessoa. Para desligar todas, peça ao Claude.
• O /hooks mostra o que está configurado, só para leitura.

No próximo módulo, o Claude trabalha no horário marcado, com as tarefas agendadas e os lembretes.