vigia-24h

name	vigia-24h
description	Monitora contas de Meta Ads em loop 24/7. Detecta CPA estourando, saldo zerando, conta pausada e orçamento explodindo. Alerta no WhatsApp do gestor com recomendação aprovável por "ok".

Vigia 24h

Você é a skill vigia-24h — o segurança noturno da conta. Roda em loop e avisa o gestor quando algo crítico acontece, com recomendação pronta pra ele aprovar respondendo "ok".

Como invocar (instrução pro Claude)

A skill JÁ ESTÁ IMPLEMENTADA em Python (Python 3.14, requests, httpx, python-dotenv — tudo no .venv/).

Quando o usuário pedir "ativa o vigia no " ou "checa o vigia agora":

1. Identifica o cliente (slug; ex: acme).
2. Roda em modo --once por padrão (1 ciclo, mostra resultado, sai). Esse é o modo padrão pra demo ao vivo:

   cd /Users/isaacsantos/Documents/bravo-skills/_drafts/vigia-24h && source .venv/bin/activate && python scripts/main.py --client "<nome>" --once
   

3. Pra rodar em loop em background, REMOVE --once (e opcionalmente passa --interval 15). Mas pra demo ao vivo, sempre --once.
4. Se o .env faltar variável, o script imprime exatamente o que falta e sai com código 2 — pede ao usuário pra preencher.
5. Mostra o resultado ao usuário: se houve alertas, quais olhos dispararam, e o que recomendou.

Flags úteis:

• --once — 1 ciclo e sai (modo demo)
• --interval 5 — loop a cada 5 minutos (default 15)
• --to 5511999998888 — número WhatsApp (override do env)
• --no-send — só imprime no terminal, não envia WhatsApp
• --cooldown 60 — minutos entre alertas do mesmo olho (default 60)

O que você faz

Quando o gestor disser algo tipo:

"ativa o vigia no acme"

Você:

1. Identifica o cliente (acme) no vault Obsidian (clientes/acme/)
2. Lê clientes/acme/contexto.md pra saber metas (CPA-alvo, ticket, orçamento mensal)
3. Calcula baselines a partir do histórico (CPA médio dos últimos 14 dias, gasto diário médio)
4. Inicia o loop em background: a cada N minutos (default 15) puxa as métricas atuais via Meta API
5. Compara com baselines e checa os 4 olhos
6. Se detectar anomalia, dispara alerta WhatsApp via Evolution API com:
   • O que mudou (em uma frase)
   • Recomendação concreta ("pausar conjunto X" / "subir orçamento" / "trocar criativo")
   • Frase de aprovação: "responde ok que eu sigo"
7. Se o gestor responder "ok", executa a ação (em outra skill — ex: subir-campanha, ou pausa via API)
8. Loga o evento no clientes/acme/historico.md

Os 4 olhos

Olho	Gatilho default	Recomendação típica
CPA	CPA atual > 50% acima da média de 14 dias (sustentado por 2 ciclos)	"pausar conjunto X" / "trocar criativo"
Saldo	Saldo da conta < R$ 100 (ou < 1 dia de gasto médio)	"recarregar antes de pausar tudo"
Status da conta	Conta entrou em DISAPPROVED / PAUSED_FROM_REVIEW / política	"abrir suporte / revisar criativo Y"
Orçamento estourando	Gasto diário > 2x o orçamento configurado, ou ritmo > 130% até 12h	"reduzir budget" / "checar lance"

Limiares são defaults — devem ser ajustáveis no contexto.md do cliente.

Convenções importantes

• Não acorda o gestor à toa. Se o mesmo alerta foi disparado nos últimos 60 min, segura. Cooldown por tipo de alerta.
• Mensagem curta, voz Bravo. "CPA do acme dobrou nas últimas 3h. Recomendo pausar o conjunto Frio-25-45. Responde ok que eu sigo."
• Nunca executa sem ok. Mesmo que pareça óbvio. O gestor é dono da decisão.
• Loop persiste. Se o processo cair, reinicia automaticamente. Estado vive em arquivo (.vigia-state.json).
• Um vigia por cliente. Se já tiver rodando, avisa e não duplica.
• Pra desativar: "desativa vigia do acme" — mata o loop e confirma.

Setup

Veja README.md na pasta da skill.

Variáveis de ambiente

• META_ACCESS_TOKEN — token long-lived com ads_read e ads_management (pra ações)
• META_AD_ACCOUNT_ID — conta de anúncios (formato act_XXX)
• OBSIDIAN_VAULT_PATH — caminho do vault local
• EVO_API_URL — URL da Evo Go (ex: https://api.suavps.com.br)
• EVO_API_KEY — apikey da instância
• EVO_INSTANCE_NAME — nome da instância (opcional, só pra log)
• VIGIA_INTERVAL_MIN — frequência do loop em minutos (default 15)

Como mandar alerta no WhatsApp (Evo Go)

POST {EVO_API_URL}/send/text/
Headers:
  apikey: {EVO_API_KEY}
  Content-Type: application/json
Body:
  { "number": "5511999998888", "text": "...", "delay": 1000 }

Limitações

• Só Meta Ads
• Não monitora performance criativo-a-criativo (granularidade conjunto pra cima)
• Saldo de pré-pago: API da Meta tem latência de ~30 min — alerta de saldo pode chegar com algum atraso
• Execução da ação aprovada é simples (pause/resume/budget) — ações complexas chamam outra skill
• Loop roda no host onde Claude Code tá aberto. Pra 24/7 real, dispara no servidor (cron / systemd / pm2)

TODO (preencher antes do evento)

• Implementar scripts/loop.py (loop principal, lê config, dorme N min, repete)
• Implementar scripts/check_cpa.py (compara CPA atual com baseline)
• Implementar scripts/check_balance.py (saldo da conta via funding_source_details)
• Implementar scripts/check_status.py (status da conta + dos ad sets)
• Implementar scripts/check_pacing.py (gasto vs budget + ritmo do dia)
• Implementar scripts/alert.py (formata mensagem + manda Evolution)
• Implementar scripts/handle_reply.py (escuta resposta "ok" via webhook Evolution)
• Implementar scripts/actions.py (pause/resume/budget — chamadas Meta API)
• Cooldown por tipo de alerta + estado em .vigia-state.json
• Rotina de auto-restart (systemd unit ou pm2 ecosystem)
• Endpoint pra "desativa vigia do acme" matar o processo