Skip to main content
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. Quando você retoma com --resume ou --continue, Claude Code restaura tarefas que não tenham expirado, exceto aquelas listadas em Limitações. Para agendamento que sobreviva independentemente de qualquer sessão, use Routines para criar uma rotina na nuvem, configure uma tarefa agendada do Desktop ou use GitHub Actions.

​
Comparar opções de agendamento

Claude Code oferece três maneiras de agendar trabalho recorrente ou único:
Use tarefas em cloud para trabalho que deve ser executado de forma confiável sem sua máquina. Use tarefas Desktop quando você precisa de acesso a arquivos e ferramentas locais. Use /loop para polling rápido durante uma sessão.

​
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 uma skill como o prompt, por exemplo /loop 20m /review-pr 1234, para re-executar essa skill a cada iteração. Um disparo agendado executa apenas skills que Claude tem permissão para invocar por conta própria. Os seguintes chegam a Claude como texto simples em vez de executar:

​
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.
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:
Em uma sessão onde a ferramenta Monitor está disponível, Claude pode usá-la diretamente quando você pede um cronograma /loop dinâmico. 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. A lista mostra seu despertar pendente como uma tarefa única, portanto um despertar agendado para :00 ou :30 pode ser executado um pouco antes. A expiração de sete dias também se aplica ao loop.
Intervalos escolhidos dinamicamente e o prompt de manutenção integrado funcionam em todos os provedores, e com busca de sinalizador de recurso desativada. No Amazon Bedrock, Claude Platform no AWS, Google Cloud’s Agent Platform e Microsoft Foundry, ou com busca desativada, ambos exigem Claude Code v2.1.248 ou posterior.

​
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.
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

Crie um arquivo loop.md para substituir 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 Claude Code o ignora 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:
.claude/loop.md
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 de ritmo próprio 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 uma vez que a tarefa está completa. Claude chama a ferramenta ScheduleWakeup com stop: true, o que cancela o despertar pendente imediatamente. Se uma iteração terminar sem reagendar ou parar, Claude Code agenda um despertar de fallback cerca de 20 minutos depois e encerra o loop quando essa iteração também não reagendar. Loops em um intervalo fixo continuam em execução até que você os cancele como qualquer outra tarefa agendada 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.
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.
Estas são as ferramentas subjacentes que Claude usa: 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

Uma tarefa agendada pode ser executada em um horário diferente do que seu agendamento indica. Se as tarefas de todas as sessões fossem executadas exatamente no horário agendado, muitas delas chamariam a API no mesmo momento, então Claude Code desloca o horário de execução de cada tarefa. Tarefas recorrentes são executadas com atraso, exceto uma tarefa executada a cada cinco minutos, escrita como */5 * * * *. Tarefas únicas agendadas para a hora cheia ou a meia hora são executadas um pouco mais cedo. Para ver quando uma tarefa vence novamente, leia a linha abaixo da chamada CronCreate de Claude no seu terminal. A linha mostra esse horário após o agendamento, por exemplo next run 10:21 AM. Para verificar novamente mais tarde, peça a Claude para listar suas tarefas e procure next run nas linhas abaixo da chamada CronList. Os horários da próxima execução nessas linhas exigem Claude Code v2.1.299 ou posterior.

​
Quanto atraso uma tarefa recorrente tem

A menos que seja executada a cada cinco minutos, uma tarefa recorrente inicia cada execução com um atraso de até metade do intervalo até a próxima execução, e de no máximo 30 minutos. Sua tarefa se enquadra em um destes três casos:
  • Execuções com espaçamento uniforme: uma tarefa com intervalos iguais, como a cada hora, diariamente ou a cada 10 minutos, é executada com o mesmo número de minutos de atraso todas as vezes, inclusive quando a sessão está ociosa.
  • Execuções com espaçamento irregular: uma tarefa com intervalos desiguais, como uma agendada para :00 e :15 de cada hora, pode ser executada com um número diferente de minutos de atraso em cada uma.
  • A cada cinco minutos: uma tarefa escrita como */5 * * * * não sofre atraso. Uma execução exatamente cinco minutos após a anterior começaria depois que um cache de prompt de cinco minutos tivesse expirado, então cada execução começa 15 segundos antes.
Encontre seu agendamento na primeira coluna desta tabela para ver quando cada uma de suas execuções começa. Por exemplo, 7,37 * * * * agenda uma tarefa para :07 e :37, que estão a 30 minutos de distância, então seu atraso fica em algum ponto entre 0 e 15 minutos. Se o atraso dessa tarefa for de 14 minutos, ela é executada às :21 e :51 de cada hora. Alterar o agendamento para um minuto diferente move o horário de execução, e um atraso ainda é adicionado a ele.

​
Quando uma tarefa única é executada mais cedo

Uma tarefa única agendada para :00 ou :30 é executada até 90 segundos mais cedo. Claude Code não desloca uma tarefa única agendada para qualquer outro minuto, então, quando o horário for importante, agende-a fora da hora cheia e da meia hora: 3 9 * * * em vez de 0 9 * * *.

​
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. Colocar a sessão em segundo plano leva tarefas /loop para uma sessão em segundo plano, que continua em execução sem um terminal.
  • 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.
  • Quando você retoma uma sessão com claude --resume ou claude --continue, Claude Code restaura as tarefas agendadas com CronCreate, exceto tarefas recorrentes que expiraram e tarefas únicas cujo tempo agendado já passou. Um /loop auto-paced não é restaurado, então execute /loop novamente para reiniciá-lo. Tarefas de Bash em segundo plano e tarefas de monitor nunca são restauradas ao retomar.
  • Com busca de feature flag desativada, Claude Code armazena uma tarefa que você pediu para manter entre sessões no arquivo .claude/scheduled_tasks.json do projeto. Quando o diretório .claude ou esse arquivo é um symlink, Claude Code retorna um erro em vez de agendar a tarefa. Uma tarefa salva é executada apenas na pasta do projeto onde você a criou. Se você copiar o arquivo para outra pasta, como um novo worktree, as sessões lá listam as tarefas copiadas, mas não as executam, então crie a tarefa novamente nessa pasta.
Para automação orientada por cron que precisa ser executada sem supervisão: