Guia
Hooks do Claude Code, explicados: o que são e o que você pode construir
Resposta curta: Os hooks permitem que o Claude Code execute seu comando quando uma ferramenta inicia, quando ele pede permissão ou quando uma rodada termina. Como funcionam e como o Herdbell os usa.
Um hook é um pequeno comando que um agente executa em um momento definido. Claude Code, Codex e Cursor oferecem suporte a eles de alguma forma, e são a maneira limpa de outro programa acompanhar o que um agente está fazendo sem entrar em nenhuma conta nem ler a tela.
A ideia em um parágrafo
Você diz ao agente: quando isto acontecer, execute este comando. O agente o executa e entrega a ele uma descrição curta do evento. O comando pode apenas registrá-lo (para enviar uma notificação, por exemplo) ou, em alguns eventos, pode devolver uma resposta que o agente usa.
Momentos em que você pode usar hooks
Os nomes exatos de eventos e as configurações variam entre agentes e versões, então confira a documentação de cada agente antes de escrever o seu.
- Uma sessão começa ou termina, ou você envia um prompt.
- Uma ferramenta está prestes a rodar ou acabou de rodar.
- O agente pede permissão para fazer algo.
- O agente termina a rodada (um evento Stop).
Onde eles ficam
Em um arquivo de configurações: no Claude Code é ~/.claude/settings.json, no Codex ~/.codex/hooks.json e no Cursor ~/.cursor/hooks.json. Editar esses arquivos à mão é válido, e é também como uma ferramenta como o Herdbell se conecta.
Como o Herdbell os usa
- Ao conectar, o Herdbell faz backup do arquivo e depois adiciona seu próprio pequeno comando para os eventos de que precisa.
- Na maioria dos eventos ele apenas escuta, para poder mostrar o que o agente está fazendo.
- Em uma solicitação de permissão, ele espera sua resposta e a devolve, então Allow e Deny têm efeito. No fim de uma rodada, ele pode manter o agente aberto para que sua resposta volte ao mesmo chat.
- Se você não responder a tempo, ele se retira, e o agente volta ao próprio prompt. Desconectar remove apenas os hooks do Herdbell.
Perguntas frequentes
Os hooks precisam de chave de API ou login?
Não. Um hook é um comando local no seu Mac. O Herdbell os usa para nunca precisar entrar em um agente nem chamar um modelo de IA.
Um hook pode quebrar meu agente?
Um mal escrito pode deixá-lo lento ou confuso, por isso o Herdbell faz backup das suas configurações antes, mantém seus hooks pequenos e se retira quando você não responde. Você pode desconectá-lo quando quiser.