Hooks Claude Code que Poupam Horas

🎯 Hooks Claude Code que Poupam Horas

Sou o Diogo Köpke, CEO da KopkAI, e vou mostrar-te como parar de vigiar o Claude enquanto ele trabalha. Este guia ensina-te a criar hooks que te avisam quando o Claude Code termina uma tarefa. Nada de refrescar o ecrã de cinco em cinco minutos, nada de interromper o que estás a fazer para verificar se já acabou. Vais aprender a configurar notificações automáticas por Slack, email, webhook ou até luzes inteligentes na tua casa.

No final deste guia, vais conseguir montar um sistema de notificações que te poupa entre 8 a 15 horas por mês. Vais ter instruções passo a passo, links para todas as ferramentas (a maioria gratuitas), um caso prático com números reais e uma checklist para não te perderes. Isto não é teoria, é implementação directa para quem tem um negócio pequeno e não pode desperdiçar tempo a fazer de babysitter a um agente de IA.

💸 O Problema (e o que te está a custar)

Quando mandas o Claude Code executar uma tarefa que demora vinte ou trinta minutos, ficas preso. Não sabes quando acaba, por isso ou ficas ali a vigiar o ecrã ou voltas de dez em dez minutos para verificar. Cada interrupção quebra a tua concentração e custa-te mais quinze minutos para voltares ao ritmo. Se isto acontece três vezes por dia, são quarenta e cinco minutos perdidos só em contexto switching. Por semana, são quase quatro horas. Por mês, quinze horas.

Quinze horas por mês a um custo médio de 30€ por hora (conservador para um dono de negócio em Portugal) são 450€ mensais. Por ano, 5400€ de tempo desperdiçado só porque não tens um sistema de notificações. E isto é só o tempo directo. Não estou a contar a frustração, o cansaço mental de estar sempre alerta, ou as tarefas importantes que adias porque estás a vigiar um agente.

🚀 A Solução

A solução é criar hooks que disparam automaticamente quando o Claude Code termina a tarefa. Um hook é um gatilho programado que executa uma acção específica num momento definido. No teu caso, o momento é "Claude terminou" e a acção pode ser "envia-me um Slack", "pisca a luz do escritório" ou "toca um som no telemóvel". Não precisas de ser programador. Precisas de seguir uma sequência lógica e usar ferramentas que já existem.

Antes: mandas o Claude executar, ficas vinte minutos a refrescar o ecrã, perdes o fio ao que estavas a fazer, voltas a arrancar do zero. Depois: mandas o Claude executar, vais fazer outra coisa produtiva, recebes notificação Slack quando acaba, voltas e continuas. A diferença são quinze horas por mês recuperadas. Quinze horas que podes usar para fechar vendas, melhorar processos ou simplesmente não trabalhar até às nove da noite.

🛠️ Pré-requisitos

Vais precisar de algumas ferramentas para montar o sistema. A maior parte é gratuita ou tem planos free suficientes para começar. Aqui está o que precisas antes de avançar:

• Claude.ai (https://claude.ai) — 0€/mês no plano free, 20€/mês no Pro. Precisas de conta activa para usar Claude Code.
• Claude Code (https://docs.anthropic.com/en/docs/build-with-claude/claude-code) — incluído na subscrição Claude, interface de desenvolvimento onde vais trabalhar.
• Slack (https://slack.com) — 0€/mês no plano free para equipas até 10 pessoas. Vais usar para receber notificações.
• Zapier ou Make (https://zapier.com ou https://make.com) — Zapier free permite 100 tarefas/mês, Make permite 1000 operações/mês grátis. Vais usar para conectar o Claude a outros serviços.
• Webhook.site (https://webhook.site) — gratuito, serve para testar se os teus hooks estão a funcionar antes de conectar ao Slack.
• Python 3.8+ instalado (https://python.org/downloads) — gratuito, necessário se quiseres correr scripts locais. Tempo de instalação: 10 minutos.
• Conta Gmail ou Outlook (https://gmail.com) — gratuito, para receber notificações por email como fallback.

Dificuldade: média-baixa. Se sabes criar uma conta online e seguir instruções passo a passo, consegues. Tempo total de setup: entre 45 minutos a 1h30 dependendo da tua familiaridade com estas ferramentas. Custo: 0€ se usares só planos free, até 40€/mês se optares por planos pagos de todas as ferramentas (desnecessário no início).

📋 Implementação Passo a Passo

Passo 1: Configurar Webhook de Teste

Vai a https://webhook.site e copia o URL único que te aparece no ecrã. Este URL vai servir para testares se o Claude consegue enviar notificações quando termina uma tarefa. Guarda este URL num ficheiro de texto porque vais usá-lo várias vezes. O Webhook.site mostra-te em tempo real todas as chamadas HTTP que recebe, o que é perfeito para debugging.

Resultado esperado: tens um URL do tipo https://webhook.site/abc123-def456 guardado e pronto a usar. Quando o Claude enviar dados para este URL, vais ver aparecer no ecrã do Webhook.site.

Passo 2: Criar Script de Notificação no Claude Code

Abre o Claude Code e cria um novo ficheiro Python chamado notify.py. Vais escrever um script simples que envia um POST request para o teu webhook quando executado. O código base é este: import requests; def notify(message): requests.post('TEU_WEBHOOK_URL', json={'status': 'done', 'message': message}); notify('Tarefa concluída'). Substitui TEU_WEBHOOK_URL pelo URL que copiaste no passo anterior. Este script vai ser o teu mecanismo de notificação.

Porque é que isto importa: este script é a ponte entre o Claude terminar uma tarefa e tu receberes a notificação. Sem isto, não há comunicação automática. O Claude pode terminar o trabalho dele, mas tu nunca saberás a menos que vás verificar manualmente.

Resultado esperado: tens um ficheiro notify.py funcional que, quando executado, envia uma notificação para o Webhook.site. Testa executando python notify.py no terminal e verifica se aparece no Webhook.site.

Passo 3: Integrar Notificação nas Tarefas do Claude

Agora vais modificar os teus scripts de trabalho para chamarem o notify.py quando terminam. Se tens um script que processa dados ou gera relatórios, adiciona no final: import notify; notify.notify('Processamento de dados terminado'). Coloca esta linha sempre depois da última operação importante, antes do script terminar. Desta forma, cada vez que o Claude termina a tarefa, o hook dispara automaticamente.

Porque é que isto importa: esta integração transforma tarefas mudas em tarefas comunicativas. O Claude deixa de trabalhar em silêncio e passa a avisar-te activamente quando termina. É a diferença entre teres de verificar constantemente e seres notificado proactivamente.

Resultado esperado: todos os teus scripts principais têm agora uma linha de notificação no final. Quando executas qualquer um deles, recebes confirmação automática no Webhook.site.

Passo 4: Conectar Webhook ao Slack

Vai ao Slack, cria um canal dedicado chamado #notificacoes-claude ou #automacao. Nas definições do canal, procura por Integrations e adiciona Incoming Webhooks. O Slack vai gerar um webhook URL específico para este canal. Copia esse URL. Agora volta ao teu ficheiro notify.py e substitui o webhook.site URL pelo Slack webhook URL. A partir deste momento, as notificações vão directamente para o teu Slack em vez do site de teste.

Porque é que isto importa: Slack é onde tu e a tua equipa já estão. Receber notificações lá em vez de num site random significa que vês imediatamente quando algo termina, sem teres de vigiar outro separador. Podes até configurar notificações mobile para receber alertas onde quer que estejas.

Resultado esperado: quando executas os teus scripts, recebes mensagens no canal Slack #notificacoes-claude. Podes estar noutra janela ou até fora do computador e vês a notificação mobile.

Passo 5: Adicionar Notificação Email como Backup

Instala a biblioteca smtplib (já vem com Python) e modifica o notify.py para enviar também um email. Configura com as credenciais SMTP do Gmail ou Outlook. O código adicional é simples: import smtplib; server = smtplib.SMTP('smtp.gmail.com', 587); server.starttls(); server.login('teu@email.com', 'password'); server.sendmail('teu@email.com', 'teu@email.com', 'Tarefa terminada'); server.quit(). Isto garante que mesmo se o Slack falhar, recebes notificação.

Porque é que isto importa: redundância. Se o Slack está em baixo ou o webhook falha por qualquer razão, tens backup por email. Para tarefas críticas que demoram horas a correr, não podes arriscar perder a notificação porque um serviço falhou.

Resultado esperado: além da notificação Slack, recebes também um email na inbox sempre que uma tarefa termina. Tens dois canais de comunicação independentes.

Passo 6: Configurar Notificações para Erros

Modifica o notify.py para ter uma função separada notify_error(message) que envia notificações com formato diferente quando algo corre mal. Usa try/except nos teus scripts principais e chama notify_error dentro do except block. Exemplo: try: [tua tarefa]; notify.notify('Sucesso') except Exception as e: notify.notify_error(f'Erro: {str(e)}'). Assim sabes imediatamente se uma tarefa falhou em vez de descobrir horas depois.

Porque é que isto importa: não queres descobrir às seis da tarde que a tarefa que mandaste correr às dez da manhã falhou e não produziu nada. Notificações de erro imediatas permitem-te reagir rápido, corrigir o problema e voltar a executar sem perder o dia inteiro.

Resultado esperado: recebes notificações distintas para sucesso e erro. Quando algo falha, sabes imediatamente qual foi o erro específico e podes agir.

Passo 7: Integrar com Luzes Inteligentes (Opcional)

Se tens luzes Philips Hue, LIFX ou similares, podes fazer piscar uma luz quando o Claude termina. Usa a API da marca das tuas luzes (Hue API em https://developers.meethue.com, LIFX em https://api.developer.lifx.com). Adiciona ao notify.py uma chamada HTTP à API das luzes para mudar cor ou piscar. Exemplo LIFX: requests.put('https://api.lifx.com/v1/lights/all/state', headers={'Authorization': 'Bearer TOKEN'}, json={'power': 'on', 'color': 'green', 'brightness': 1.0}).

Porque é que isto importa: notificações físicas são impossíveis de ignorar. Podes estar noutra sala a trabalhar e ver a luz mudar. É especialmente útil quando tens tarefas que demoram uma ou duas horas e não queres estar colado ao computador.

Resultado esperado: quando o Claude termina uma tarefa, a luz do teu escritório pisca verde. Estás noutro sítio da casa e sabes imediatamente sem olhar para o telemóvel ou computador.

Passo 8: Testar o Sistema Completo

Executa uma tarefa real no Claude Code com todas as notificações activas. Monitoriza o Slack, o email e as luzes (se configuraste). Verifica se recebes todas as notificações no momento certo. Testa também provocar um erro propositado para garantir que as notificações de erro funcionam. Ajusta timings e mensagens conforme necessário. Este teste completo garante que o sistema está robusto antes de dependeres dele para trabalho crítico.

Porque é que isto importa: um sistema de notificações que falha 20% das vezes é pior do que não ter sistema nenhum. Crias falsa confiança. Testar exaustivamente antes de ir para produção garante que quando confias no sistema para te avisar, ele cumpre.

Resultado esperado: tens confiança total no sistema. Sabes que quando o Claude termina, vais ser notificado em menos de 10 segundos por pelo menos dois canais diferentes.

🧰 Ferramentas e Recursos

💼 Caso Prático

Imagina uma firma de contabilidade com 6 pessoas em Lisboa. Três contabilistas usam Claude Code para processar declarações fiscais e gerar relatórios mensais de clientes. Cada relatório demora entre vinte a quarenta minutos a processar. Antes de implementar hooks, cada contabilista verificava o progresso manualmente cinco a sete vezes por relatório. Com quinze relatórios por semana por pessoa, eram 225 interrupções semanais. Cada interrupção roubava três minutos de contexto switching. Total: 675 minutos por semana, ou 11 horas e 15 minutos.

Implementaram o sistema de hooks em dois dias. Primeiro dia: configuraram Slack, webhooks e scripts básicos de notificação. Segundo dia: testaram com relatórios reais e ajustaram mensagens. Depois de activo, cada contabilista passou a mandar o Claude processar relatórios e voltava ao trabalho normal. Recebiam notificação Slack quando terminava. Recuperaram 11 horas semanais, 44 horas mensais. A 30€/hora (conservador para contabilistas certificados), são 1320€ mensais recuperados. Em seis meses, 7920€. O custo de implementação foi zero, só usaram ferramentas gratuitas.

Timeline: semana 1 setup e teste, semana 2 primeiros resultados visíveis, mês 1 sistema completamente integrado no workflow diário. Resistência inicial de um contabilista mais velho que preferia o método antigo, mas cedeu quando viu os colegas saírem uma hora mais cedo todos os dias.

⚠️ Erros Comuns e Como Evitar

Erro 1: Não Testar com Tarefas Reais

Muita gente testa só com scripts dummy de 10 segundos e assume que funciona. Quando vão para produção com tarefas de uma hora, descobrem problemas de timeout, memória ou credenciais que expiram. Como evitar: depois dos testes rápidos, faz sempre um teste com uma tarefa real que demora pelo menos vinte minutos. Identifica problemas antes de dependeres do sistema.

Erro 2: Usar Só Um Canal de Notificação

Confiar só no Slack ou só no email é arriscado. Serviços falham, webhooks têm rate limits, emails vão para spam. Quando isso acontece numa tarefa crítica que demora três horas, perdes a tarde inteira. Como evitar: configura sempre pelo menos dois canais independentes. Slack + email é o mínimo. Para tarefas muito longas, adiciona SMS via Twilio ou notificação física.

Erro 3: Mensagens de Notificação Genéricas

Receber "Tarefa concluída" quando tens quatro tarefas a correr em paralelo não ajuda nada. Tens de abrir todas para descobrir qual terminou. Como evitar: usa mensagens descritivas com nome da tarefa, timestamp e dados relevantes. Exemplo: "Relatório Q1 2024 gerado às 14:37, 234 registos processados".

Erro 4: Não Configurar Notificações de Erro

Muita gente só configura notificações de sucesso. Quando uma tarefa falha silenciosamente, descobrem horas depois. Como evitar: trata erros explicitamente com try/except e envia notificações de erro com detalhes do problema. Usa formato visual diferente (emoji vermelho, cor diferente) para destacar imediatamente.

Erro 5: Hardcoded Credentials nos Scripts

Meter passwords e API tokens directamente no código é má ideia. Se partilhas o script ou fazes commit para git, expões credenciais. Como evitar: usa variáveis de ambiente. Cria um ficheiro .env (e adiciona ao .gitignore) com as tuas credenciais. Carrega com python-dotenv. Mantém segurança sem sacrificar funcionalidade.

Erro 6: Não Documentar o Setup

Montas o sistema, funciona bem, passam três meses. Precisas de adicionar uma nova notificação e já não te lembras como configuraste. Como evitar: cria um README.md simples com os passos de configuração, URLs dos webhooks, credenciais (sem expor passwords), e como adicionar novas notificações. Leva dez minutos a escrever, poupa horas no futuro.

Erro 7: Spam de Notificações

Configurar notificações para absolutamente tudo torna-as inúteis. Recebes cinquenta mensagens por dia e paras de prestar atenção. Como evitar: reserva notificações só para tarefas que demoram mais de quinze minutos ou são críticas. Tarefas rápidas não precisam de hook, vês o resultado directamente.

✅ Checklist de Implementação

Fase 1: Setup Inicial

• Criar conta Claude.ai e aceder ao Claude Code
• Criar workspace Slack e canal #notificacoes-claude
• Registar conta Webhook.site e guardar URL de teste
• Instalar Python 3.8+ e biblioteca requests
• Configurar Incoming Webhook no Slack e copiar URL

Fase 2: Construção do Sistema

• Criar ficheiro notify.py com função de notificação básica
• Testar notificação para Webhook.site e validar recepção
• Substituir URL de teste por Slack webhook no código
• Adicionar função notify_error para tratamento de erros
• Configurar notificação email como backup
• Criar ficheiro .env com credenciais e tokens

Fase 3: Testes e Validação

• Testar notificação de sucesso com tarefa dummy de 5 minutos
• Testar notificação de erro provocando exception propositado
• Validar recepção em todos os canais (Slack, email, luzes)
• Executar tarefa real de produção com notificações activas
• Verificar timestamps e conteúdo das mensagens
• Ajustar formato e timing conforme necessário

Fase 4: Produção e Documentação

• Integrar notify.py em todos os scripts principais
• Criar README.md com instruções de configuração
• Formar equipa sobre como interpretar notificações
• Definir SLA de resposta a notificações de erro
• Monitorizar sistema durante primeira semana completa

Preferes que isto seja feito por nós? Conhece o nosso serviço de inteligência artificial para empresas.

Guias relacionados

• Skills Claude Code Modulares
• Agentes Autónomos: Quando Confiar e Quando Não
• Mapa de Ferramentas AI Para Negócios