Sobre o projeto

agent-runner é uma ferramenta de supervisão para manter CLIs de codificação autônomas em execução contínua. Ela reinicia processos de agente após cada rodada e inclui predefinições para Claude Code, aider, gemini, codewhale, kimi e pi, além de suportar qualquer CLI com argumento de prompt por meio de configuração personalizada. A ferramenta é organizada em torno de um modelo de três camadas: a Rodada (uma invocação do agente), o Loop (um loop de reinício com captura de sinais) e o Witness (um monitor com 14 detectores e parada automática). Ela fornece 15 defesas nomeadas estruturadas como dados, incluindo orçamentos de tempo por rodada, isolamento de grupos de processos, idempotência de stash de órfãos, stashes bloqueados por SHA, classificação por diferença de conjuntos e verificações de fumaça na inicialização. Cada defesa documenta o incidente histórico que aborda e possui um teste de invariante. O componente de monitor executa 14 detectores nos logs locais do projeto supervisionado, cobrindo problemas como taxas de timeout, rodadas travadas, cadeias de órfãos, avisos e crescimento de disco, pressão de memória, falhas de rede, limitação de taxa e anomalias repetitivas. Dois detectores podem parar automaticamente o serviço quando continuar seria prejudicial: falhas de OAuth que consomem cota de API e condições críticas de disco. Um freio suave opcional pode limitar o uso de memória sob pressão sustentada. O agent-runner expõe 17 verbos de comando para gerenciamento do ciclo de vida (init, install, start, stop, restart, kill, upgrade, migrate) e observação (peek, watch, monitor, events, status, doctor). Ele suporta unidades de usuário do systemd para os processos serve e monitor, janelas programadas de execução/pausa, saída JSON para consumidores downstream e retransmissão remota de eventos por conexões SSH gerenciadas, mantendo a detecção no host. O projeto inclui documentação extensa cobrindo início rápido, referência de comandos, esquema de configuração, solução de problemas para operadores e arquitetura. É somente POSIX (Linux, macOS), testado com Python 3.11+ em x86_64 e aarch64, e licenciado sob Apache 2.0.