Agente de Autoagendamento

Quando Usar

• Use quando o usuário solicitar trabalho recorrente, agendado, de "batimento cardíaco" (heartbeat) ou em loop para o agente.
• Use quando precisar escolher entre cron, agendadores externos, hooks ou agendamento de agente integrado.

O agendamento requer uma solicitação direta do usuário; um guia ou uma entrada na lista de tarefas não é permissão para criar trabalho em segundo plano. Preserve o fuso horário, a cadência, as preferências de notificação e as condições de parada; atualize um trabalho correspondente existente em vez de duplicá-lo. Mensagens externas e postagens exigem autorização explícita.

Primeiro, inspecione o host real: prefira seu agendador/heartbeat suportado quando disponível (incluindo automações do Codex); caso contrário, use um relógio externo explicitamente autorizado. As capacidades do host não são determinadas apenas pelo nome do runtime.

O cron tradicional de cinco campos tem granularidade de um minuto; outros agendadores diferem. Prefira verificações orientadas por eventos e uma cadência apropriada. Evite temporizadores de LLM apertados e loops indefinidos.

Acampamento A — Agentes de execução única, você controla o relógio

Estes executam uma vez e saem (amnésicos, a menos que sejam retomados). Agende-os externamente.

claude -p "PROMPT" --output-format json --allowedTools "Read"  # Claude Code
codex exec --json "PROMPT"                                                # Codex
pi run "PROMPT"                                                           # Pi

Envolva em um relógio:

# 1. cron (>= 1 min floor)
*/10 * * * * cd /path/to/project && pi run "check X and report" >> ~/agent.log 2>&1
# 2. systemd timer (Linux, survives reboot, better logging) — OnUnitActiveSec=10min
# 3. dumb loop (sub-minute, or no cron available)
# If an external loop is required, bound its lifetime and implement a stop flag and overlap lock.
# Do not install an indefinite model-calling loop by default.

Armadilhas (cada uma quebra execuções não supervisionadas se ignorada):

• Permissões travam para sempre. Use as permissões de escopo restrito suportadas pelo host para a tarefa acordada. Não desative o sandboxing ou aprove comandos amplamente para evitar um prompt não supervisionado; relate aprovações necessárias indisponíveis.
• Use saída JSON (--output-format json / --json) para que o wrapper analise os resultados de forma determinística.
• Execuções são amnésicas. Retome o ID exato da tarefa/sessão gravada ou persista o estado de escopo privado. --last pode selecionar uma tarefa não relacionada e é inadequado para um agendamento multi-projeto não supervisionado.

Pi NÃO tem agendador/loop/heartbeat embutido por design — apenas relógio externo (ou uma extensão TS para temporizadores do lado do agente).

cmux — apenas orquestração, SEM agendador

cmux não tem temporizador/monitor/cron. Três maneiras de executá-lo em loop: orquestrador-dirigido (send → sleep → read-screen em seu próprio relógio), um wrapper dumb while-sleep, ou — preferencialmente — orientado por eventos via cmux notify + hooks de terminal OSC, que é mais barato e responsivo do que polling. read-screen não é interruptivo, seguro para polling.

Para um monitor, permaneça quieto enquanto o estado não mudar, a menos que o usuário solicite atualizações periódicas; notifique sobre mudanças significativas, conclusão, falha ou entrada necessária. (Claude Code pode preencher uma mensagem prevista do usuário após terminar — isso é Claude, não o usuário.)

Acampamento B — Agendador integrado do Hermes

O gateway do Hermes dispara a cada 60 segundos e executa trabalhos agendados em sessões isoladas e novas. Verifique o estado primeiro:

hermes gateway install            # user-level ( --system to survive reboot)
hermes cron create "every 1h" "summarize new emails and report" --skill himalaya
hermes cron create "0 9 * * *" "post daily standup"      # cron expr
hermes cron create "30m" "one-shot reminder in 30 min"   # one-shot delay

Exclusivo do Hermes: modo zero-token (execute um script, entregue stdout literalmente — use para watchdogs), encadeamento (context_from canaliza a saída de um trabalho para o próximo), loops auto-termináveis e segurança de loop (sessões agendadas não podem criar mais trabalhos cron — não agende de dentro de um trabalho agendado). Cada execução é uma sessão nova: o prompt deve carregar todo o contexto.

Padrão de Heartbeat

Um tick rápido e recorrente controla muitas verificações mais lentas por tarefa: o tick lê uma lista de tarefas + timestamps last_run por tarefa e age apenas nas tarefas que estão agendadas. No Hermes, use um trabalho recorrente (modo zero-token quando nada está agendado); no Acampamento A, use um loop while-sleep. Defina horários de funcionamento e permaneça em silêncio quando nada estiver agendado — sem ruído vazio.

Verifique se dispara (antes de relatar sucesso)

1. Acampamento A: o arquivo de log cresce após um intervalo, ou execute o comando encapsulado uma vez manualmente → JSON limpo, saída 0.

…