Aula 15Hooks: ações automáticas

🖥️ Versão Desktop. Nesta versão do curso, você usa o Claude Code no app Claude Desktop, na aba Code. Quase tudo é feito por janelas e botões. Quando uma aula pedir para digitar um comando, ela mostra exatamente o que digitar. Nesta aula, você não digita nenhum comando: o exercício é um pedido em português e um clique num arquivo. A parte opcional do fim usa o /status, para conferir a versão, e o terminal integrado do app, para deixar um script pronto para rodar.

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. O app lê os mesmos arquivos de configurações que o terminal.

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? O app já avisa: quando uma sessão termina uma tarefa e você não está olhando para ela, ele mostra uma notificação do sistema. Isso não precisa de ação automática.

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, e rodar quando o Claude trabalha nessa pasta.

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 abrir no app a pasta de outra pessoa, abra uma sessão na sua pasta de sempre e peça ao Claude para 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

Na aba Code, abra uma sessão 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, clique no caminho .claude/settings.json quando ele aparecer na resposta: o app abre o arquivo no painel ao lado da conversa. Você não precisa entender cada linha, porque o Claude acabou de explicar. O /hooks, que mostra essa lista num menu, é da versão do terminal.

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 canal do time. A notificação do app já existe sem hook (veja o 💡 do começo da aula)

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. O app lê os mesmos arquivos de settings que o terminal, e os hooks disparam nos mesmos eventos.

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. Edições diretas nos arquivos de settings costumam valer sem reiniciar nada: o Claude Code percebe a mudança sozinho.

Para conferir o que está configurado, abra o arquivo: clique no caminho .claude/settings.json quando ele aparecer na conversa ou no diff, e o app o mostra no painel de arquivos. Ou peça ao Claude: "liste os hooks configurados e de onde vem cada um". O comando /hooks, que mostra essa lista com a origem de cada hook e o texto completo do que ele roda, é da versão do terminal.

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: rode chmod +x .claude/hooks/formatar.sh no terminal integrado do app (Ctrl+`, ou Terminal, na barra de título da sessão), ou peça ao Claude para fazer isso. Os exemplos também usam o jq para ler o JSON; instale-o se ainda não tiver. Se o hook não achar o jq ou o npx, confira se eles funcionam no terminal do seu sistema e reinicie o app: ele nem sempre herda todo o ambiente do seu shell. 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. No app, confira a versão com /status (linha Claude Code); se for anterior, use Claude → Check for Updates (no Mac) ou Help → Check for Updates (no Windows) e abra uma sessão nova. 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.

ℹ️ Numa sessão que você abre no app com a opção worktree, o Claude Code lê os hooks da raiz do checkout principal, roda os comandos lá, e o CLAUDE_PROJECT_DIR aponta para essa raiz, não para a cópia do worktree. Se um script precisar da pasta em que o Claude está trabalhando, leia o campo cwd do JSON que o hook recebe.

Hooks pessoais, em ~/.claude/settings.json, valem só no seu computador, nas sessões Local do app: as sessões na nuvem (as sessões Cloud do app e a web) 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

No terminal, o Claude Code pergunta se você confia numa pasta antes de rodar os hooks dela. Já um claude -p ou uma sessão do Agent SDK nunca pergunta e conta a pasta como confiada, e aí os hooks commitados num repositório rodam mesmo numa pasta em que você nunca confiou. No app, conte com que os hooks de uma pasta possam rodar logo na primeira sessão nela: por isso, a explicação do Claude vem antes de abrir a pasta de outra pessoa.

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.
• 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.
• Na versão do terminal, dá para desligar os hooks de uma execução só, seja o que for que o projeto diga, com claude --settings '{"disableAllHooks": true}'.

Para testar

1. Peça ao Claude um hook PostToolUse com matcher Edit|Write que rode o formatador do seu projeto. Se o app pedir aprovação para mexer na pasta .claude, aprove. Depois, clique no caminho .claude/settings.json na conversa e confira o hook no painel de arquivos.
2. Peça ao Claude uma pequena edição e confira, no diff, que o arquivo saiu formatado.
3. Peça um hook PreToolUse que bloqueie rm -rf com exit 2. Abra o terminal integrado (Ctrl+`) e rode chmod +x .claude/hooks/bloquear-rm.sh (ou peça ao Claude). Depois, peça ao Claude para "limpar a pasta build com rm -rf" e veja como ele reage ao bloqueio.
4. Peça ao Claude para commitar .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. Na aba Code, clique em + New. Na linha abaixo da caixa de mensagem, escolha Local e a pasta da sua página. Antes da primeira mensagem, escolha Manual no seletor de modo, na mesma linha.
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. Na resposta, clique no caminho .claude/settings.json: o arquivo abre no painel ao lado, com as duas regras e nenhuma ação automática. Se o caminho não aparecer, peça: "mostre o caminho do arquivo .claude/settings.json deste projeto".
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 app já avisa quando uma sessão termina uma tarefa e você não está olhando.
• Ela roda com as suas permissões: só de quem você confia, e com a explicação do Claude antes de abrir a pasta de outra pessoa. Para desligar todas, peça ao Claude.
• Para ver o arquivo, clique no caminho do .claude/settings.json na conversa: ele abre no painel ao lado.

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