Claude Code agora oferece suporte a hooks

 (docs.anthropic.com)
20 pontos por GN⁺ 2025-07-02 | 4 comentários | Compartilhar no WhatsApp
  • O Claude Code passou a ter a funcionalidade de hooks personalizados, permitindo controlar o comportamento do app com mais precisão e de forma repetível sem depender das escolhas do LLM
  • Isso possibilita várias automações, como personalização de notificações, formatação automática de código e rastreamento de logs de comandos
  • Funciona antes/depois da execução de comandos, no disparo de notificações e no momento em que a resposta é concluída, e pode ser gerenciado em nível de projeto, usuário e enterprise por meio de arquivos de configuração
  • Por meio da estrutura do arquivo de configuração e do esquema de matcher, é possível executar apenas hooks específicos em determinados momentos de chamada de ferramentas
  • A entrada é enviada em formato JSON e a saída controla resultado e feedback por meio de exit code ou JSON
  • Como os hooks executam automaticamente comandos de shell com todas as permissões do usuário, é preciso ter cuidado com segurança e proteção

Introdução

  • Os hooks do Claude Code são comandos de shell personalizados executados automaticamente em cada etapa do ciclo de execução do código
  • Com isso, torna-se possível ter automação consistente a cada vez, em vez de depender de execuções opcionais feitas pelo LLM

  • Principais exemplos de uso

    • Notificações: fornecer notificações personalizadas ao usuário quando houver espera por entrada
    • Formatação automática: executar prettier ou gofmt automaticamente após editar arquivos
    • Logging: registrar e agregar os comandos executados para rastreamento ou depuração
    • Feedback: fornecer feedback automático quando for gerado código que não segue as regras da base de código
    • Permissões personalizadas: bloquear alterações em diretórios sensíveis ou arquivos de produção
  • Como funcionam como código de sistema, e não como prompt, são executados de forma determinística em todas as vezes → maior confiabilidade da automação
  • Como os hooks executam diretamente comandos de shell com todas as permissões do usuário, é necessário validar a segurança.

Exemplo de configuração

  • Ex.: registrar um hook para que o Claude deixe logs sempre antes de executar um comando Bash
    1. Entrar no menu de configuração de hooks com o comando /hooks e selecionar o evento PreToolUse
    2. Adicionar o matcher Bash (aplica-se apenas a comandos Bash)
    3. Registrar e salvar o comando do hook (se escolher User settings, aplica-se a todos os projetos)
    4. Verificar a configuração com /hooks ou conferir diretamente o arquivo ~/.claude/settings.json

Estrutura de configuração

  • Os hooks são agrupados com base em matcher e cada matcher pode ter vários hooks em array
    • Ex.: string única (correspondência exata), expressão regular, ou vazio para aplicar a todos os eventos
  • Tipos de arquivo de configuração
    • ~/.claude/settings.json: configuração global do usuário
    • .claude/settings.json: configuração do projeto
    • .claude/settings.local.json: configuração local (não compartilhada)
    • configuração de política enterprise

Principais eventos de hook

  • PreToolUse: executado antes da chamada da ferramenta; se necessário, pode bloquear a execução (principais matchers: Bash, Write, Edit, Grep etc.)
  • PostToolUse: executado logo após a ferramenta; suporta os mesmos matchers
  • Notification: executado ao enviar notificações
  • Stop: executado após a conclusão da resposta

Exemplos de matcher

  • Task: tarefa do agente
  • Bash: comando de shell
  • Glob: correspondência de padrão de arquivo
  • Grep: busca de conteúdo
  • Read: leitura de arquivo
  • Edit, MultiEdit: modificação de arquivo
  • Write: gravação de arquivo
  • WebFetch, WebSearch: tarefas web

Formatos de entrada e saída

  • Entrada: JSON enviado via stdin (inclui informações da sessão e dados específicos por evento)
    • Ex.: em PreToolUse inclui tool_input; em PostToolUse acrescenta tool_response
  • Saída:
    • exit code 0: execução normal; stdout é exibido ao usuário
    • exit code 2: bloqueio; stderr é enviado ao Claude como feedback (em PreToolUse, bloqueia a execução da ferramenta)
    • outros códigos: erro; apenas stderr é exibido ao usuário
    • Controle avançado: ao retornar JSON em stdout, é possível controlar o fluxo em detalhe, como com "continue" false ou "decision": "block"

Integração com ferramentas MCP

  • Também há suporte para ferramentas baseadas em Model Context Protocol (MCP), que podem ser alvo de forma seletiva por meio do padrão especial de nomenclatura (mcp____)

Recomendações de segurança

  • Como hooks trazem o risco de executar comandos arbitrários do sistema, regras de segurança como validação de entrada, checagem de caminhos, exclusão de arquivos sensíveis e uso de caminhos absolutos são indispensáveis
  • Alterações na configuração não são refletidas imediatamente; é usado um snapshot no início da sessão, e mudanças externas exibem um aviso

Ambiente de execução e depuração

  • Cada hook tem limite máximo de 60 segundos, execução paralela e funciona no diretório de trabalho e ambiente atuais
  • É possível depurar verificando a configuração em /hooks, testando comandos diretamente e conferindo exit code e saída
  • O processo de execução e os resultados podem ser vistos no modo transcript (Ctrl-R)

Leituras relacionadas

4 comentários

 
shakespeare 2025-07-02

Por favor, façam também uma versão para Windows T_T
 
nalbam 2025-07-06

Use o WSL.
 
slowmo 2025-07-08

Como as especificações do meu PC são baixas, no WSL do Windows algumas tarefas com o Claude Code (por exemplo, build do projeto, executar servidor web local etc.) ficam lentas demais.
Há a opção de executar só essas tarefas manualmente fora do WSL, mas como isso é incômodo e tem limitações, desde que o Gemini CLI foi lançado no Windows tenho usado principalmente o Gemini CLI em vez do Claude Code.
 
GN⁺ 2025-07-02
Comentários no Hacker News

  • Fiquei frustrado com o hábito do Claude Code Opus 4 de não adicionar um retorno no fim dos arquivos.
    Como é preciso reiniciar o claude para testar novos hooks, foi muito mais eficiente usar um script que permite continuar editando dentro da sessão.
    Esse script aplica formatadores em arquivos C e scripts shell e, nos demais arquivos, apenas corrige retornos ausentes.
    AIs como o Claude são fracas em dividir o problema adequadamente e às vezes tentam fazer as coisas de formas estranhas, então acabei corrigindo várias vezes algo como o exemplo de hook acima: salvar um arquivo JSON no disco, extrair só o caminho e salvar de novo, e então passar esse caminho para save-hook.sh.
    Consegui fazer o que queria em 10 minutos, mas perdi ainda mais tempo tentando mandar um grande passo de uma vez.

  • Ouvimos dizer que a IA vai substituir desenvolvedores, mas ainda cabe às pessoas decidir quem vai configurar esses hooks e sugerir novas funcionalidades.
    Esse tipo de trabalho relacionado a tooling vai continuar existindo até a IA evoluir a ponto de ter essa ideia por conta própria e aplicá-la a outras IAs.

    • Fazendo uma analogia com marcenaria, vejo o momento atual como uma transição das ferramentas manuais para as ferramentas elétricas.
      Quem entende os fundamentos consegue usar bem a ferramenta, mas agora estamos numa fase em que, em vez de fazer algo delicadamente à mão, usamos uma serra de bancada para trabalhar mais rápido; é mais eficiente, mas também pode ser mais perigoso.

    • É parecido com a alegação de que máquinas agrícolas como colheitadeiras combinadas substituiriam empregos na agricultura.
      Faz sentido imaginar que toda a força de trabalho simplesmente viraria operadora de máquinas?
      A visão aqui é que, seja com ferramentas de automação, agricultura ou IA, o valor não está apenas numa transição simples.

    • Como na famosa história da "Terra sobre o casco de uma tartaruga", depois do surgimento da IA dá para entrar num loop infinito de "então quem vai gerenciar essa IA?".
      Já há casos em que se pede ao Claude Code para atualizar o próprio CLAUDE.md, então também não é totalmente impossível fazê-lo modificar os próprios hooks.
      Mas é interessante como, ao estilo de Jurassic Park, a pergunta "devemos fazer isso?" tende a ficar de fora.

    • Tanto a opinião de que a IA vai reduzir empregos de desenvolvimento quanto a pergunta sobre quem vai configurar os hooks estão corretas.
      O ponto é enfatizar que o avanço tecnológico não se resume de forma simplista a aumentar ou diminuir o número de empregos; ele elimina alguns e ao mesmo tempo cria outros.

    • Na verdade, para a maioria das pessoas esse tipo de tarefa não é desenvolvimento, e sim manutenção, DevOps e coisas do tipo.
      Mesmo em produtos SaaS, há muito trabalho mais ligado à operação do que a código, o que difere bastante do desenvolvimento mais "raiz" em que os usuários do HN costumam pensar.

  • Estou realmente animado com a chegada desse recurso.
    Hooks devem ter um papel importante na engenharia de contexto dos agentes e na validação de desempenho em tempo de execução.
    Também parecem expansíveis para vários cenários, como compliance corporativo ou monitoramento de comportamento.
    Também foi impressionante a Anthropic dar suporte logo após a sugestão em uma issue no GitHub.
    Link da issue relacionada

    • Na prática, eu uso uma extensão do VS Code chamada cline.bot em vez do Claude Code.
      Acho que esse tipo de recurso vai virar um trunfo indispensável em todos os agentes de programação.

  • O que me faz gostar desse recurso é que ele permite escrever regras de controle de execução de comandos complexos diretamente, sem precisar contornar isso com CLAUDE.md.
    Por exemplo,
    docker compose exec django python manage.py test
    pode ser permitido, enquanto
    docker compose exec django python manage.py makemigrations
    pode ser bloqueado.

    • Isso nesse nível já dá para implementar em .Claude/settings.json.

  • Acho que teria sido ainda melhor se esse recurso funcionasse como o próprio servidor MCP.
    Dá para imaginar hooks expostos como ferramentas MCP com nomes pré-definidos, o agente descobrindo automaticamente os hooks sem precisar conhecer a implementação interna, e assim reutilizando o servidor MCP ou aproveitando isso em outros agentes.

  • O Claude Code esquece com frequência as instruções do arquivo CLAUDE.md e os pontos principais do codebase, então é preciso ficar lembrando toda hora.
    Estou na expectativa para ver se esta atualização pode corrigir esse problema.

    • Por exemplo: "Não use retorno antecipado em função void! Está escrito no CLAUDE.md que esse padrão é proibido!"
      O Claude lê o CLAUDE.md e responde: "22 segundos, 2.6k tokens..."
      "Você está certo!"

  • Compartilhando alguns hooks de exemplo.
    Post com exemplos de criação de hooks e automação de workflow
    É bom ver o Claude Code atingir um nível equivalente ao Cursor, com suporte a linting e type checking após modificar código.

  • Queria que o Cursor também tivesse isso.
    Por enquanto estou improvisando e resolvendo mais ou menos com uma combinação de várias regras.

    • Como alguém que não usa Cursor, ainda fico me perguntando se existe motivo para usar isso.

  • Acho que esse recurso fecha uma grande lacuna funcional que existia até agora.
    Por causa da forma como o Claude Code cria commits, os hooks normais do Git em geral não funcionavam, então eu usava a gambiarra de instruir pelo CLAUDE.md que ele automatizasse a formatação de código com o Qlty CLI, mas o Claude não conseguia fazer isso com consistência, o que era frustrante.
    Com essa mudança, dá para obter resultados mais determinísticos.
    Embora os eventos que aceitam hooks ainda sejam limitados, espero que no futuro também fique fácil adicionar hooks em eventos de git commit e push.
    GitHub do Qlty CLI

    • A propósito, o Claude lida muito bem com Java.
      Ele entende perfeitamente meu guia de estilo, até minhas preferências de indentação, a ponto de entregar código Java sem precisar reformatar.
      Também acerta JavaDoc com bastante precisão, o que me impressionou.
      Imagino que ele tenha sido treinado com uma quantidade enorme de código Java corporativo.

    • Fico curioso para saber por que os hooks normais do git não funcionam direito no claude code.

    • Husky e lint-staged funcionaram normalmente, mas os Pre Commit Hooks não funcionaram.

  • Pelo que entendi rapidamente, esse recurso não consome contexto e, diferente do MCP, não depende de o Claude decidir quando executar; é uma estrutura de automação em que o usuário define diretamente o comportamento para cada uso de ferramenta.