Executar prompts em um cronograma

Use /loop e as ferramentas de agendamento cron para executar prompts repetidamente, pesquisar status ou definir lembretes únicos em uma sessão do Claude Code.

Tarefas agendadas permitem que Claude execute novamente um prompt automaticamente em um intervalo. Use-as para pesquisar uma implantação, cuidar de um PR, verificar uma compilação de longa duração ou lembrar-se de fazer algo mais tarde na sessão. Para reagir a eventos conforme eles acontecem em vez de pesquisar, consulte Channels: seu CI pode enviar a falha para a sessão diretamente. Para manter a sessão funcionando turno após turno até que uma condição seja atendida em vez de em um intervalo, consulte /goal.

As tarefas têm escopo de sessão: elas vivem na conversa atual e param quando você inicia uma nova. Retomar com --resume ou --continue traz de volta qualquer tarefa que não tenha expirado: uma tarefa recorrente criada nos últimos 7 dias, ou uma única cujo tempo agendado ainda não passou. Para agendamento que sobreviva independentemente de qualquer sessão, use Routines para criar uma rotina na infraestrutura gerenciada pela Anthropic, configure uma tarefa agendada do Desktop ou use GitHub Actions.

Comparar opções de agendamento

Claude Code offers three ways to schedule recurring or one-off work:

Execute um prompt repetidamente com /loop

A skill agrupada /loop bundled skill é a maneira mais rápida de executar um prompt repetidamente enquanto a sessão permanece aberta. Tanto o intervalo quanto o prompt são opcionais, e o que você fornece determina como o loop se comporta.

Você também pode passar outro comando como o prompt, por exemplo /loop 20m /review-pr 1234, para re-executar uma skill salva ou comando a cada iteração.

Execute em um intervalo fixo

Quando você fornece um intervalo, Claude o converte em uma expressão cron, agenda o trabalho e confirma a cadência e o ID do trabalho.

/loop 5m check if the deployment finished and tell me what happened

O intervalo pode preceder o prompt como um token simples como 30m, ou seguir como uma cláusula como every 2 hours. As unidades suportadas são s para segundos, m para minutos, h para horas e d para dias.

Os segundos são arredondados para o minuto mais próximo, pois o cron tem granularidade de um minuto. Os intervalos que não mapeiam para um passo cron limpo, como 7m ou 90m, são arredondados para o intervalo mais próximo que funciona e Claude informa qual foi escolhido.

Deixe Claude escolher o intervalo

Quando você omite o intervalo, Claude escolhe um dinamicamente em vez de executar em um cronograma cron fixo. Após cada iteração, ele escolhe um atraso entre um minuto e uma hora com base no que observou: esperas curtas enquanto uma compilação está terminando ou um PR está ativo, esperas mais longas quando nada está pendente. O atraso escolhido e o motivo dele são impressos no final de cada iteração.

O exemplo abaixo verifica CI e comentários de revisão, com Claude esperando mais tempo entre iterações uma vez que o PR fica silencioso:

/loop check whether CI passed and address any review comments

Quando você pede um cronograma /loop dinâmico, Claude pode usar a ferramenta Monitor diretamente. Monitor executa um script em segundo plano e transmite cada linha de saída de volta, o que evita pesquisa completamente e geralmente é mais eficiente em tokens e responsivo do que re-executar um prompt em um intervalo.

Um loop agendado dinamicamente aparece em sua lista de tarefas agendadas como qualquer outra tarefa, portanto você pode listá-lo ou cancelá-lo da mesma forma. As regras de jitter não se aplicam a ele, mas a expiração de sete dias se aplica: o loop termina automaticamente sete dias após você iniciá-lo.

Execute o prompt de manutenção integrado

Quando você omite o prompt, Claude usa um prompt de manutenção integrado em vez de um que você fornece. A cada iteração, ele trabalha através do seguinte, em ordem:

• continuar qualquer trabalho inacabado da conversa
• cuidar do pull request do branch atual: comentários de revisão, execuções de CI falhadas, conflitos de mesclagem
• executar passes de limpeza, como caças a bugs ou simplificação quando nada mais está pendente

Claude não inicia novas iniciativas fora desse escopo, e ações irreversíveis como envio ou exclusão apenas prosseguem quando continuam algo que a transcrição já autorizou.

/loop

Um /loop simples executa este prompt em um intervalo escolhido dinamicamente. Adicione um intervalo, por exemplo /loop 15m, para executá-lo em um cronograma fixo. Para substituir o prompt integrado pelo seu próprio padrão, consulte Personalize o prompt padrão com loop.md.

Personalize o prompt padrão com loop.md

Um arquivo loop.md substitui o prompt de manutenção integrado pelas suas próprias instruções. Ele define um único prompt padrão para /loop simples, não uma lista de tarefas agendadas separadas, e é ignorado sempre que você fornece um prompt na linha de comando. Para agendar prompts adicionais junto com ele, use /loop <prompt> ou peça a Claude diretamente.

Claude procura o arquivo em dois locais e usa o primeiro que encontra.

O arquivo é Markdown simples sem estrutura obrigatória. Escreva como se estivesse digitando o prompt /loop diretamente. O exemplo a seguir mantém um branch de lançamento saudável:

Check the `release/next` PR. If CI is red, pull the failing job log,
diagnose, and push a minimal fix. If new review comments have arrived,
address each one and resolve the thread. If everything is green and
quiet, say so in one line.

Edições em loop.md entram em vigor na próxima iteração, portanto você pode refinar as instruções enquanto um loop está em execução. Quando nenhum loop.md existe em nenhum local, o loop volta ao prompt de manutenção integrado. Mantenha o arquivo conciso: conteúdo além de 25.000 bytes é truncado.

Pare um loop

Para parar um /loop enquanto ele está aguardando a próxima iteração, pressione Esc. Isso limpa o despertar pendente para que o loop não dispare novamente. As tarefas que você agendou pedindo a Claude diretamente não são afetadas por Esc e permanecem no lugar até que você as delete.

Em modo de ritmo próprio, Claude também pode encerrar o loop por conta própria ao não agendar o próximo despertar uma vez que a tarefa está comprovadamente completa. Loops em um intervalo fixo continuam em execução até que você os pare ou sete dias se passem.

Defina um lembrete único

Para lembretes únicos, descreva o que você deseja em linguagem natural em vez de usar /loop. Claude agenda uma tarefa de disparo único que se deleta após ser executada.

remind me at 3pm to push the release branch

in 45 minutes, check whether the integration tests passed

Claude fixa o tempo de disparo em um minuto e hora específicos usando uma expressão cron e confirma quando será acionado.

Gerencie tarefas agendadas

Peça a Claude em linguagem natural para listar ou cancelar tarefas, ou referencie as ferramentas subjacentes diretamente.

what scheduled tasks do I have?

cancel the deploy check job

Nos bastidores, Claude usa estas ferramentas:

Cada tarefa agendada tem um ID de 8 caracteres que você pode passar para CronDelete. Uma sessão pode conter até 50 tarefas agendadas por vez.

Como as tarefas agendadas são executadas

O agendador verifica a cada segundo se há tarefas vencidas e as enfileira com baixa prioridade. Um prompt agendado é acionado entre seus turnos, não enquanto Claude está no meio de uma resposta. Se Claude estiver ocupado quando uma tarefa vencer, o prompt aguarda até que o turno atual termine.

Todos os horários são interpretados em seu fuso horário local. Uma expressão cron como 0 9 * * * significa 9h onde você está executando Claude Code, não UTC.

Jitter

Para evitar que cada sessão atinja a API no mesmo momento de tempo real, o agendador adiciona um deslocamento determinístico aos tempos de disparo:

• Tarefas recorrentes disparam até 30 minutos após o horário agendado (ou até metade do intervalo, para tarefas que são executadas com mais frequência que por hora). Um trabalho por hora agendado para :00 pode disparar em qualquer lugar até :30.
• Tarefas únicas agendadas para o topo ou fundo da hora disparam até 90 segundos mais cedo.

O deslocamento é derivado do ID da tarefa, portanto a mesma tarefa sempre obtém o mesmo deslocamento. Se o tempo exato for importante, escolha um minuto que não seja :00 ou :30, por exemplo 3 9 * * * em vez de 0 9 * * *, e o jitter único não será aplicado.

Expiração de sete dias

Tarefas recorrentes expiram automaticamente 7 dias após a criação. A tarefa é acionada uma última vez e depois se deleta. Isso limita quanto tempo um loop esquecido pode ser executado. Se você precisar que uma tarefa recorrente dure mais tempo, cancele e recrie-a antes de expirar, ou use Routines ou tarefas agendadas do Desktop para agendamento durável.

Referência de expressão cron

CronCreate aceita expressões cron padrão de 5 campos: minute hour day-of-month month day-of-week. Todos os campos suportam curingas (*), valores únicos (5), passos (*/15), intervalos (1-5) e listas separadas por vírgula (1,15,30).

O dia da semana usa 0 ou 7 para domingo até 6 para sábado. A sintaxe estendida como L, W, ? e aliases de nome como MON ou JAN não é suportada.

Quando tanto o dia do mês quanto o dia da semana são restritos, uma data corresponde se qualquer campo corresponder. Isso segue a semântica padrão do vixie-cron.

Desabilite tarefas agendadas

Defina CLAUDE_CODE_DISABLE_CRON=1 em seu ambiente para desabilitar o agendador completamente. As ferramentas cron e /loop ficam indisponíveis e qualquer tarefa já agendada para de ser acionada. Consulte Variáveis de ambiente para a lista completa de sinalizadores de desabilitação.

Limitações

O agendamento com escopo de sessão tem limitações inerentes:

• As tarefas só são acionadas enquanto Claude Code está em execução e ocioso. Fechar o terminal ou deixar a sessão sair para tudo.
• Sem recuperação para disparos perdidos. Se o tempo agendado de uma tarefa passar enquanto Claude está ocupado em uma solicitação de longa duração, ela dispara uma vez quando Claude fica ocioso, não uma vez por intervalo perdido.
• Iniciar uma conversa nova limpa todas as tarefas com escopo de sessão. Retomar com claude --resume ou claude --continue restaura tarefas que não expiraram: tarefas recorrentes dentro de sete dias de criação, e tarefas únicas cujo tempo agendado ainda não passou. Tarefas de Bash em segundo plano e tarefas de monitor nunca são restauradas ao retomar.

Para automação orientada por cron que precisa ser executada sem supervisão:

• Routines: executadas na infraestrutura gerenciada pela Anthropic em um cronograma, via chamada de API ou em eventos do GitHub
• GitHub Actions: use um gatilho schedule em CI
• Tarefas agendadas do Desktop: executadas localmente em sua máquina