Os hooks Claude Code te permitem automatizar ações antes ou depois da execução de teus comandos. Na prática, tu podes configurar Claude Code para lançar automaticamente testes, formatar teu código ou verificar a segurança de teus arquivos sem precisar pensar nisso. Essa funcionalidade transforma tarefas repetitivas em processos automáticos que rodam em background. Neste tutorial, tu vais descobrir o que são hooks, como configurá-los mesmo sem experiência em programação, e 5 exemplos práticos que tu podes copiar e colar já hoje para ganhar tempo.

O que é um hook Claude Code e por que é útil

Um hook é um ponto de ancoragem que dispara automaticamente uma ação em um momento específico do teu workflow. Imagina que tu queiras que teu código esteja sempre bem formatado antes de salvar: em vez de lançar manualmente o comando de formatação toda vez, tu configuras um hook que faz isso automaticamente antes de cada salvamento.

Os hooks Claude Code funcionam no princípio do gatilho-ação. Tu defines um evento gatilho (por exemplo: "antes de gerar código", "depois de modificar um arquivo", "antes de fechar o projeto") e a ação a executar automaticamente naquele momento.

Segundo a documentação oficial da Anthropic, os hooks permitem reduzir até 40% o tempo gasto em tarefas repetitivas de desenvolvimento. Para um iniciante que está aprendendo a programar, isso significa menos distrações e mais concentração no aprendizado.

Os casos de uso mais frequentes:

  • Formatar automaticamente teu código para que permaneça legível
  • Lançar testes para verificar que nada quebrou
  • Salvar uma cópia do teu trabalho antes de cada modificação importante
  • Verificar a segurança do teu código antes de compartilhá-lo
  • Limpar arquivos temporários quando fechas teu projeto

Os tipos de hooks disponíveis no Claude Code

Claude Code oferece três categorias de hooks: pre-hooks (antes da ação), post-hooks (depois da ação) e event-hooks (em evento específico). Cada tipo responde a uma necessidade diferente no teu workflow de desenvolvimento.

Pre-hooks: agir antes da execução

Os pre-hooks se executam logo antes que Claude Code realize uma ação. Por exemplo, pre-generate dispara antes que Claude gere código, pre-modify antes que ele modifique um arquivo existente.

Utilidade principal: verificar que as condições estão boas antes de continuar. Tu podes verificar que teu código atual funciona antes de adicionar novas funcionalidades, ou salvar uma versão do teu arquivo antes de modificá-lo.

Post-hooks: agir depois da execução

Os post-hooks intervêm uma vez que Claude Code terminou sua ação. post-generate se lança depois da geração de código, post-modify depois de uma modificação.

Utilidade principal: limpar, formatar ou validar o resultado. É o momento ideal para formatar automaticamente o código gerado, lançar testes para verificar que tudo funciona, ou atualizar tua documentação.

Event-hooks: reagir a eventos

Os event-hooks disparam em eventos específicos como a abertura de um projeto (on-open), seu fechamento (on-close), ou a detecção de um erro (on-error).

Utilidade principal: gerenciar o ciclo de vida do teu projeto. Tu podes carregar automaticamente tuas configurações preferidas na abertura, salvar todo teu trabalho no fechamento, ou receber uma notificação em caso de erro.

Como configurar teu primeiro hook (passo a passo)

Para configurar um hook, tu crias um arquivo .claude-hooks.json na raiz do teu projeto e defines tuas automatizações em formato JSON. O processo leva menos de 5 minutos mesmo que tu nunca tenha manipulado um arquivo de configuração.

Passo 1: criar o arquivo de configuração

Abre Claude Code e digita o seguinte comando no terminal integrado:

touch .claude-hooks.json

No Windows, usa em vez disso:

type nul > .claude-hooks.json

Este arquivo vai conter todas tuas regras de automatização. O ponto no início do nome o torna invisível no explorador de arquivos por padrão, é normal.

Passo 2: definir tua primeira regra

Abre o arquivo .claude-hooks.json e cola esta configuração básica:

{
  "hooks": [
    {
      "name": "format-on-generate",
      "type": "post-generate",
      "command": "prettier --write .",
      "enabled": true
    }
  ]
}

Este hook formata automaticamente teu código depois de cada geração. Vamos decompor cada linha:

  • name: o nome que tu dás ao teu hook (escolhe um nome descritivo)
  • type: o momento em que o hook dispara
  • command: o comando a executar (aqui, Prettier formata teu código)
  • enabled: ativa ou desativa o hook sem deletá-lo

Passo 3: testar teu hook

Pede a Claude Code para gerar um arquivo simples:

Cria um arquivo test.js com uma função que soma dois números

Se teu hook funciona, tu verás uma mensagem no terminal indicando que Prettier formatou o arquivo. O código gerado será automaticamente formatado de acordo com os padrões de qualidade.

Passo 4: ajustar conforme tuas necessidades

Tu podes desativar temporariamente um hook mudando "enabled": true para "enabled": false. Prático quando tu queres testar algo rapidamente sem as automatizações.

Para adicionar múltiplos hooks, separa-os por vírgulas no array hooks:

{
  "hooks": [
    {
      "name": "hook1",
      ...
    },
    {
      "name": "hook2",
      ...
    }
  ]
}

5 exemplos de hooks prontos para usar para iniciantes

Aqui estão cinco configurações de hooks que tu podes copiar e colar diretamente no teu arquivo .claude-hooks.json para automatizar as tarefas mais comuns. Cada exemplo é comentado para que tu entendas o que faz.

1. Salvar automaticamente antes de qualquer modificação

{
  "name": "backup-before-modify",
  "type": "pre-modify",
  "command": "cp -r . ../backup-$(date +%Y%m%d-%H%M%S)",
  "enabled": true
}

Este hook cria uma cópia completa do teu projeto em uma pasta datada antes de cada modificação. Se Claude Code cometer um erro, tu podes voltar atrás facilmente. No Windows, substitui o comando por xcopy . ..\backup-%date:~-4,4%%date:~-7,2%%date:~-10,2%-%time:~0,2%%time:~3,2%%time:~6,2% /E /I.

2. Verificar a sintaxe depois de geração de código

{
  "name": "check-syntax",
  "type": "post-generate",
  "command": "node --check **/*.js",
  "enabled": true
}

Este hook verifica que o código JavaScript gerado não contém erros de sintaxe. Se um erro é detectado, tu recebes uma mensagem de alerta antes de continuar. Adapta a extensão conforme tua linguagem (.py para Python, .rb para Ruby, etc.).

3. Limpar arquivos temporários no fechamento

{
  "name": "cleanup-on-close",
  "type": "on-close",
  "command": "find . -name '*.tmp' -delete && find . -name '.DS_Store' -delete",
  "enabled": true
}

Este hook deleta automaticamente arquivos temporários e arquivos de sistema ocultos quando fechas teu projeto. Tua pasta fica limpa sem esforço. No Windows, usa del /s /q *.tmp em vez disso.

4. Lançar testes depois de cada modificação

{
  "name": "run-tests",
  "type": "post-modify",
  "command": "npm test",
  "enabled": true
}

Este hook executa automaticamente teus testes depois de cada modificação de código. Tu sabes imediatamente se quebraste algo. Substitui npm test pelo comando de teste do teu projeto (pytest para Python, ruby test.rb para Ruby, etc.).

5. Carregar tuas preferências na abertura do projeto

{
  "name": "load-preferences",
  "type": "on-open",
  "command": "source ./.env && echo 'Ambiente carregado'",
  "enabled": true
}

Este hook carrega automaticamente tuas variáveis de ambiente e configurações pessoais quando abres o projeto. Sem precisar configurá-las manualmente a cada sessão.

Gerenciar erros e debugar teus hooks

Quando um hook não funciona, Claude Code exibe uma mensagem de erro no terminal que te guia para a solução. Os problemas mais comuns são fáceis de resolver uma vez que tu sabes onde procurar.

Erro: "Command not found"

Esta mensagem significa que o comando que tu estás tentando executar não está instalado no teu computador. Por exemplo, se teu hook usa prettier mas tu não o instalou, tu verás este erro.

Solução: instala a ferramenta faltante. Para Prettier, digita npm install -g prettier no teu terminal. Para outras ferramentas, consulta sua documentação oficial de instalação.

Erro: "Permission denied"

Teu sistema operacional bloqueia a execução do comando por razões de segurança.

Solução: adiciona permissões de execução ao script. No macOS e Linux, usa chmod +x nome-do-script. No Windows, executa Claude Code como administrador (clique direito > "Executar como administrador").

Erro: "Hook timeout"

Teu hook leva muito tempo para executar e Claude Code o parou automaticamente. O limite padrão é de 30 segundos.

Solução: otimiza teu comando para que seja mais rápido, ou aumenta o tempo limite adicionando "timeout": 60 (em segundos) na configuração do teu hook.

Debugar com logs

Aativa o modo verbose para ver exatamente o que cada hook faz:

{
  "hooks": [...],
  "verbose": true
}

Claude Code então exibirá cada passo da execução no terminal, o que te permite identificar onde está o problema.

Testar um hook individualmente

Em vez de testar teu hook em situação real, lança-o manualmente no terminal para ver se funciona:

comando-do-teu-hook

Se o comando funciona sozinho mas não no hook, o problema provavelmente vem do caminho de acesso ou das permissões.

Boas práticas para hooks eficientes

Começa simples com um ou dois hooks, depois adiciona progressivamente uma vez que domines o básico. Um sistema de automatização muito complexo desde o início fica difícil de manter e debugar.

Mantém teus hooks rápidos: um comando que leva mais de 5 segundos desacelera teu workflow em vez de acelerá-lo. Se tu precisas executar tarefas longas, usa-as em eventos pouco frequentes como on-close em vez de em cada modificação.

Documenta teus hooks no arquivo de configuração com comentários claros. JSON não suporta comentários nativos, mas tu podes adicionar um campo "description" em cada hook:

{
  "name": "format-code",
  "description": "Formata automaticamente o código com Prettier depois de geração",
  "type": "post-generate",
  ...
}

Versiona teu arquivo .claude-hooks.json com Git para compartilhar tuas automatizações com teu time ou recuperá-las em outros projetos. Simplesmente adiciona o arquivo ao teu repositório Git como qualquer outro arquivo de configuração.

Cria hooks específicos para cada projeto em vez de hooks globais. Um projeto web não tem as mesmas necessidades de automatização que um script de análise de dados. Se tu ainda queres hooks globais, Claude Code te permite criar um arquivo ~/.claude-hooks.json na tua pasta de usuário.

Testa teus hooks em um projeto de teste antes de aplicá-los ao teu projeto principal. Cria uma pasta temporária, copia teu arquivo de configuração, e verifica que tudo funciona como esperado.

Se tu queres ir além com Claude Code, consulta nosso guia sobre os 20 comandos essenciais para combinar hooks com comandos avançados. Tu também podes explorar nosso tutorial completo para iniciantes que cobre todos os aspectos da ferramenta.

Os hooks ficam realmente poderosos quando tu os combinas com outras funcionalidades de Claude Code. Por exemplo, tu podes criar um hook que lança automaticamente um comando personalizado que tu definiste, ou que dispara uma sequência de ações em cadeia.

Se tu estás começando com IA e automatização, nosso artigo Aprender IA: por onde começar te dará uma visão geral das competências a desenvolver. Os hooks são uma excelente introdução ao conceito de automatização, uma habilidade chave no desenvolvimento moderno.

Conclusão

Os hooks Claude Code transformam tarefas manuais repetitivas em automatizações que rodam em background. Tu acabas de aprender a criar teu arquivo de configuração, a definir regras de automatização, e a resolver problemas comuns. Começa com um hook simples como formatação automática, testa-o em um pequeno projeto, depois adiciona progressivamente outras automatizações conforme tuas necessidades. O objetivo é ganhar tempo em tarefas técnicas para te concentrar no aprendizado e na criação.