Hooks e automação
Conecte hooks SessionStart para carregar contexto automaticamente. Use PreToolUse para bloquear comandos perigosos. Execute Claude em cron com portões de aprovação.
Hooks são comandos que o Claude Code executa em eventos de ciclo de vida específicos. Configure uma vez em ~/.claude/settings.json; eles disparam automaticamente. Hooks impõem uma disciplina que você esqueceria de outra forma: carregar STATE.md em cada sessão, verificar arquivos .env em staging antes de fazer commit. O custo de configuração é de 10 minutos. O retorno é permanente.
SessionStart dispara no momento em que uma sessão é aberta; o que ele imprime se torna contexto antes da sua primeira mensagem:
{
"hooks": {
"SessionStart": [
{
"command": "cat ~/notes/STATE.md ~/notes/MEMORY.md 2>/dev/null || true"
}
]
}
}O || true importa: não interrompa o início da sessão se os arquivos estiverem faltando. Mantenha os hooks abaixo de 50ms e não faça chamadas de rede na abertura da sessão. Precisa de dados de API atualizados? Execute um cron que escreve um arquivo local; carregue o arquivo no hook.
Mais quatro eventos de hook:
Stop: dispara quando uma sessão termina. Use para lembretes: "Antes de fechar: atualize STATE.md."
PreToolUse: dispara antes de Claude chamar uma ferramenta. Sua camada de aplicação de segurança: bloqueie comandos perigosos, registre chamadas para trilhas de auditoria. Sair com 0 permite a chamada; sair com 2 a bloqueia.
PostToolUse: dispara depois que uma ferramenta retorna. Execute um linter após uma gravação de arquivo, verifique as políticas RLS após uma migração SQL.
UserPromptSubmit: dispara quando você pressiona enter. Injete contexto ou aplique defesas contra injeção de prompt para conteúdo externo.
Um hook PreToolUse que bloqueia qualquer chamada Bash contendo rm -rf:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'rm -rf'; then echo 'BLOQUEADO: rm -rf não permitido' >&2; exit 2; fi"
}
]
}
}O campo matcher direciona uma ferramenta específica. Sem ele, o hook dispara em cada chamada de ferramenta. Use matchers para manter os hooks rápidos e direcionados.
Quando um hook não está disparando, verifique na ordem:
Sintaxe: JSON válido? Execute cat ~/.claude/settings.json | python3 -m json.tool.
Caminho do arquivo: teste o comando do hook manualmente no seu terminal.
Código de saída: está faltando || true?
Velocidade: mais de 3 segundos? Mova a parte lenta para um cron.
Duas pegadinhas de produção. Defina um campo timeout explícito em cada hook para que o comportamento permaneça previsível. E os hooks são executados em um ambiente simplificado, não no seu shell completo: se um hook precisa de uma variável de ambiente (como um token do Slack), obtenha seu .env explicitamente no comando do hook. Esta é a causa mais comum de hooks que funcionam no seu terminal, mas falham silenciosamente no Claude Code.
Claude Code acionado por Cron. O mesmo agente pode ser executado em um agendamento via claude --headless: um briefing matinal às 7h postado no Slack, monitoramento de mídia social a cada 4 horas, uma verificação de saúde de implantação a cada 30 minutos.
O padrão crítico: portões de aprovação. O cron rascunha, você revisa, o sistema envia. Um agente autônomo que envia mensagens sem revisão acabará enviando algo errado: modelo errado, público errado, momento errado. A arquitetura: o agente descobre e rascunha, o humano revisa e libera. Implementação: o agente escreve rascunhos em um canal do Slack; nada é enviado até que um humano aprove. Isso escala para dezenas de agentes sem que nenhum deles se desvie.
Construa o sistema de hooks em fases:
Fase 1 (semanas 1-2), hooks de carregamento: SessionStart carrega STATE.md e MEMORY.md; Stop lembra você de atualizar.
Fase 2 (semanas 3-4), hooks de proteção: PreToolUse bloqueia comandos irreversíveis (force-push para main, DROP TABLE, rm -rf).
Fase 3 (mês 2+), hooks de auditoria: PostToolUse verifica o que foi realmente escrito: migrações SQL faltando políticas RLS, novas rotas de API faltando limitação de taxa, segredos em qualquer arquivo escrito.
PostToolUse é mais forte que PreToolUse para auditorias porque lê o conteúdo do arquivo escrito, a verdade, não apenas o que Claude pretendia. Construa hooks em torno dos seus modos de falha reais: dois hooks que resolvem problemas reais são melhores do que dez teóricos.
SessionStart carrega o contexto, Stop lembra, PreToolUse bloqueia comandos perigosos (exit 2), PostToolUse audita o que foi escrito, e cron mais portões de aprovação transformam Claude em um sistema agendado com um humano no botão de envio. Comece com um hook: cat ~/notes/STATE.md 2>/dev/null || true em SessionStart. Adicione a próxima fase a cada mês.