Guia

Como usar hooks no Claude Code

Você quer que algo aconteça sempre, como formatar um arquivo depois que o Claude o edita ou receber um aviso quando o Claude está esperando por você, sem torcer para ele lembrar. É exatamente isso que os hooks fazem. Este guia explica o que eles são, mostra um primeiro hook passo a passo e onde colocá-los.

Atualizado em 30 de outubro de 2026

Resposta rápida: um hook é um comando de shell que o Claude Code roda automaticamente em um ponto fixo, por exemplo antes de uma ferramenta rodar, depois que um arquivo é editado ou quando o Claude precisa da sua resposta. Você adiciona hooks em uma chave hooks de um arquivo de configuração, como ~/.claude/settings.json (todos os projetos) ou .claude/settings.json (um projeto), e depois digita /hooks para confirmar que o Claude Code os enxerga.

Os nomes dos eventos, os locais dos arquivos e o comportamento abaixo vêm da documentação do Claude Code da Anthropic em outubro de 2026. O Claude Code é atualizado com frequência, então rode claude update se algo estiver faltando.

O que são hooks e por que ajudam

Instruções em um prompt ou em um arquivo CLAUDE.md são sugestões: o Claude normalmente as segue, mas quem decide é ele. Um hook é diferente. O próprio Claude Code roda o seu comando sempre que o evento acontece, então a ação é determinística. Usos típicos do guia da Anthropic:

Notificações quando o Claude está esperando uma permissão ou a sua resposta.
Formatação automática de cada arquivo depois que o Claude o edita ou grava.
Bloqueio de edições em arquivos sensíveis, como o .env ou qualquer coisa em .git/.
Acrescentar contexto, por exemplo lembrar o Claude das convenções do projeto depois que a conversa é compactada.

Alguns dos eventos mais usados são SessionStart (uma sessão começa ou é retomada), UserPromptSubmit (você envia um prompt), PreToolUse (antes de uma chamada de ferramenta, e pode bloqueá-la), PostToolUse (depois que uma chamada de ferramenta dá certo), Notification, Stop (o Claude termina de responder), PreCompact e SessionEnd. A lista completa na referência de hooks é bem maior.

Configure seu primeiro hook: uma notificação na área de trabalho

Este exemplo, adaptado do passo a passo da Anthropic, avisa você no macOS sempre que o Claude Code precisa da sua atenção.

Abra o ~/.claude/settings.json em um editor de texto. Crie o arquivo se ele não existir.
Adicione um objeto hooks com uma entrada Notification. Dentro dela vai uma lista de grupos de matcher; cada um tem um matcher (deixe como string vazia para disparar em toda notificação) e uma lista hooks com um item de "type": "command".
Defina o comando como osascript -e 'display notification "Claude Code needs your attention" with title "Claude Code"'. No Linux, o exemplo da Anthropic usa notify-send no lugar. Lembre de escapar as aspas duplas internas no JSON.
Se o arquivo já tiver uma chave hooks, adicione Notification ao lado dos eventos existentes em vez de substituir o objeto inteiro.
No Claude Code, digite /hooks. O navegador de hooks deve listar seu novo hook em Notification. Pressione Esc para voltar.
Peça ao Claude algo que precise de permissão e mude para outra janela. Uma notificação deve aparecer.

Para disparar só em algumas notificações, defina o matcher com um tipo como permission_prompt (um pedido de permissão está esperando há cerca de seis segundos) ou idle_prompt (o Claude terminou e você não digitou nada por cerca de um minuto).

Um segundo exemplo: formatar arquivos depois das edições

Para um hook de projeto, coloque a configuração em .claude/settings.json na raiz do projeto. Use o evento PostToolUse com o matcher Edit|Write, para que ele só rode depois das ferramentas que editam arquivos. O comando de exemplo da Anthropic lê o caminho editado do JSON que o Claude Code passa pela entrada padrão e o entrega ao Prettier: jq -r '.tool_input.file_path' | xargs npx prettier --write. Ele precisa do jq instalado. Um hook bem-sucedido não mostra nada na conversa; você só vai ver o arquivo reformatado.

Onde os hooks são configurados

Local	Vale para	Compartilhado?
`~/.claude/settings.json`	Todos os seus projetos	Não, só no seu computador
`.claude/settings.json`	Um projeto	Sim, pode ir para o commit
`.claude/settings.local.json`	Um projeto	Não, fica fora do git
Configurações de política gerenciada	A organização inteira	Definidas pelos administradores
O `hooks/hooks.json` de um plugin	Enquanto o plugin estiver ativado	Vem junto com o plugin
Frontmatter de uma skill	O resto da sessão depois que a skill é chamada	No arquivo da skill
Frontmatter de um subagente	Enquanto esse subagente roda	No arquivo do subagente

Para desligar os hooks, defina "disableAllHooks": true em um arquivo de configuração. Hooks das configurações gerenciadas continuam rodando, a menos que isso também seja definido lá.

Como um hook responde

Quando um evento acontece, o Claude Code envia os detalhes do evento como JSON para a entrada padrão do seu comando. Seu comando responde com o código de saída:

Saída 0: segue em frente. Em alguns eventos, como SessionStart, o texto simples impresso na saída padrão é acrescentado ao contexto do Claude.
Saída 2: bloqueia a ação quando o evento permite. Escreva o motivo na saída de erro padrão; no PreToolUse, o Claude recebe esse motivo e pode mudar de rumo.
Outros códigos: normalmente tratados como erro não bloqueante; a ação continua e a transcrição mostra um erro de hook.

Para um controle mais fino, saia com 0 e imprima um objeto JSON. Escolha uma das abordagens por hook.

Bom saber

Hooks de comando não conseguem rodar comandos de barra nem chamar ferramentas por conta própria.
O tempo limite padrão dos hooks de comando é de 10 minutos, menor em alguns eventos; defina timeout (em segundos) em cada hook para mudá-lo.
O PostToolUse não desfaz nada, porque a ferramenta já rodou. Use o PreToolUse para impedir uma ação.
O Stop dispara toda vez que o Claude termina uma resposta, não só quando uma tarefa está concluída.

Se não funcionar

O hook nunca dispara: rode /hooks e confira se ele está listado no evento certo. Os matchers diferenciam maiúsculas de minúsculas e precisam corresponder exatamente ao nome da ferramenta, por exemplo Edit, não edit.
O "/hooks" não mostra nada: confira se o JSON é válido (sem vírgulas sobrando no final nem comentários) e está no arquivo certo. As edições normalmente são reconhecidas sozinhas; se não forem, reinicie a sessão.
"hook error" na transcrição: teste o script passando um JSON de exemplo para ele por pipe e conferindo echo $?. Use caminhos absolutos ou $CLAUDE_PROJECT_DIR para os scripts, instale o jq se estiver faltando e torne os scripts executáveis com chmod +x.
Nenhuma notificação no macOS: rode o comando osascript uma vez no Terminal e depois ative Allow Notifications (Permitir Notificações) para o Script Editor (Editor de Scripts) em System Settings > Notifications (Ajustes do Sistema > Notificações).

Acompanhe o que cada sessão deixa em aberto

O plugin do Workbranch para o Claude Code usa um resumo no início da sessão: em uma pasta vinculada a um projeto do Workbranch, ele mostra o que ainda está pendente quando uma sessão começa, e dizer "save this to Workbranch" (salve isto no Workbranch) organiza as tarefas, decisões e dúvidas em aberto da sessão nesse projeto. Veja Workbranch para o Claude. Novo no Claude Code? Comece por como começar a usar o Claude Code.

Fontes

Use Claude Code with your Pro or Max plan (Central de Ajuda do Claude, conferido em 30 de outubro de 2026)
Automate actions with hooks (Claude Code docs, conferido em 30 de outubro de 2026)

Perguntas frequentes

O Claude pode escrever um hook para mim?

Sim. O guia da Anthropic diz que você pode descrever o hook que quer no prompt do Claude Code e pedir ao Claude que o adicione às suas configurações. Depois, confira o resultado com /hooks.

Um hook consegue parar o Claude mesmo no modo bypass?

Um hook PreToolUse que retorna uma decisão de negar bloqueia a ferramenta em todos os modos de permissão, inclusive bypassPermissions. É isso que torna os hooks úteis para regras que ninguém consegue desligar trocando de modo.

Existem hooks que usam um modelo em vez de um script?

Sim. Além de comandos de shell, um hook pode ser uma requisição HTTP, uma chamada a uma ferramenta MCP, um único prompt avaliado por um modelo Claude ou um hook de agente experimental com acesso a ferramentas.