Eseguire prompt in base a una pianificazione

Utilizzare /loop e gli strumenti di pianificazione cron per eseguire prompt ripetutamente, eseguire il polling dello stato o impostare promemoria una tantum all'interno di una sessione Claude Code.

Le attività pianificate con ambito di sessione consentono a Claude di rieseguire automaticamente un prompt a intervalli regolari all'interno di una sessione Claude Code. Usale per eseguire il polling di un deploy, monitorare una PR, ricontrollare una build a lunga esecuzione o ricordarti di fare qualcosa più tardi nella sessione.

[!NOTE]

Questi casi sono trattati in altre pagine:

• Reagire agli eventi man mano che si verificano invece di eseguire il polling: consulta Canali. Il tuo CI può inviare il fallimento direttamente nella sessione.
• Mantenere la sessione al lavoro turno dopo turno fino al raggiungimento di una condizione anziché a intervalli: consulta /goal.

Le attività hanno ambito di sessione. Quando riprendi con --resume o --continue, Claude Code ripristina le attività che non sono scadute, ad eccezione di quelle elencate in Limitazioni. Per una pianificazione che sopravviva indipendentemente da qualsiasi sessione, crea un'attività pianificata nel cloud, configura un'attività pianificata Desktop o usa GitHub Actions.

Confrontare le opzioni di pianificazione

Claude Code offre tre modi per pianificare lavori ricorrenti o una tantum:

[!TIP]

Utilizzate attività cloud per lavori che devono essere eseguiti in modo affidabile senza la vostra macchina. Utilizzate attività Desktop quando avete bisogno di accesso ai file e agli strumenti locali. Utilizzate /loop per il polling rapido durante una sessione.

Eseguire un prompt ripetutamente con /loop

Lo skill bundled /loop è il modo più rapido per eseguire un prompt ripetutamente mentre la sessione rimane aperta. Sia l'intervallo che il prompt sono facoltativi, e quello che fornite determina il comportamento del ciclo.

Potete anche passare uno skill come prompt, ad esempio /loop 20m /review-pr 1234, per rieseguire quello skill ad ogni iterazione. Un'esecuzione pianificata esegue solo gli skill che Claude è autorizzato a invocare autonomamente. I seguenti raggiungono Claude come testo semplice invece di essere eseguiti:

• comandi integrati come /permissions, /model, o /clear
• skill contrassegnati disable-model-invocation: true, incluso lo skill bundled /verify
• skill trattenuti da Claude da un'impostazione skillOverrides o da una regola di negazione Skill
• prompt MCP come /mcp__github__list_prs

Eseguire su un intervallo fisso

Quando fornite un intervallo, Claude lo converte in un'espressione cron, pianifica il processo e conferma la cadenza e l'ID del processo.

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

L'intervallo può precedere il prompt come token nudo come 30m, oppure seguirlo come clausola come every 2 hours. Le unità supportate sono s per secondi, m per minuti, h per ore e d per giorni.

I secondi vengono arrotondati al minuto più vicino poiché cron ha una granularità di un minuto. Gli intervalli che non si dividono uniformemente in un passo cron pulito, come 7m o 90m, vengono arrotondati all'intervallo più vicino che lo fa e Claude vi dice quale ha scelto.

Lasciare che Claude scelga l'intervallo

Quando omettete l'intervallo, Claude ne sceglie uno dinamicamente invece di eseguire su un programma cron fisso. Dopo ogni iterazione sceglie un ritardo tra un minuto e un'ora in base a quello che ha osservato: attese brevi mentre una compilazione sta terminando o una PR è attiva, attese più lunghe quando non c'è nulla in sospeso. Il ritardo scelto e il motivo sono stampati alla fine di ogni iterazione.

L'esempio seguente controlla CI e i commenti di revisione, con Claude che attende più a lungo tra le iterazioni una volta che la PR diventa silenziosa:

/loop check whether CI passed and address any review comments

In una sessione in cui lo strumento Monitor è disponibile, Claude potrebbe utilizzarlo direttamente quando chiedete un programma /loop dinamico. Monitor esegue uno script in background e trasmette ogni riga di output, il che evita completamente il polling ed è spesso più efficiente in termini di token e più reattivo rispetto alla riesecuzione di un prompt a intervalli.

Un ciclo pianificato dinamicamente appare nel tuo elenco di attività pianificate come qualsiasi altra attività, quindi puoi elencarlo o annullarlo nello stesso modo. L'elenco mostra il suo risveglio in sospeso come un'attività una tantum, quindi un risveglio pianificato per :00 o :30 può essere eseguito un po' in anticipo. Anche la scadenza di sette giorni si applica al ciclo.

[!NOTE]

Gli intervalli scelti dinamicamente e il prompt di manutenzione integrato funzionano su ogni provider, e con il fetching dei feature flag disattivato. Su Amazon Bedrock, Claude Platform su AWS, Google Cloud's Agent Platform e Microsoft Foundry, o con il fetching disattivato, entrambi richiedono Claude Code v2.1.248 o successivo.

Eseguire il prompt di manutenzione integrato

Quando omettete il prompt, Claude utilizza un prompt di manutenzione integrato invece di uno che fornite. Ad ogni iterazione lavora attraverso quanto segue, in ordine:

• continuare qualsiasi lavoro non terminato dalla conversazione
• prendersi cura della pull request del ramo corrente: commenti di revisione, esecuzioni CI non riuscite, conflitti di merge
• eseguire passaggi di pulizia come cacce ai bug o semplificazione quando non c'è nulla di altro in sospeso

Claude non avvia nuove iniziative al di fuori di tale ambito, e le azioni irreversibili come il push o l'eliminazione procedono solo quando continuano qualcosa che il trascritto ha già autorizzato.

/loop

Un /loop nudo esegue questo prompt a un intervallo scelto dinamicamente. Aggiungete un intervallo, ad esempio /loop 15m, per eseguirlo su un programma fisso invece. Per sostituire il prompt integrato con il vostro predefinito, vedere Personalizzare il prompt predefinito con loop.md.

Personalizzare il prompt predefinito con loop.md

Create un file loop.md per sostituire il prompt di manutenzione integrato con le vostre istruzioni. Definisce un singolo prompt predefinito per un /loop nudo, non un elenco di attività pianificate separate, e Claude Code lo ignora ogni volta che fornite un prompt sulla riga di comando. Per pianificare prompt aggiuntivi insieme ad esso, utilizzate /loop <prompt> o chiedete direttamente a Claude.

Claude cerca il file in due posizioni e utilizza il primo che trova.

Il file è Markdown semplice senza struttura richiesta. Scrivete come se steste digitando il prompt /loop direttamente. L'esempio seguente mantiene un ramo di rilascio sano:

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.

Le modifiche a loop.md hanno effetto alla successiva iterazione, quindi potete perfezionare le istruzioni mentre un ciclo è in esecuzione. Quando nessun loop.md esiste in nessuna posizione, il ciclo ritorna al prompt di manutenzione integrato. Mantenete il file conciso: il contenuto oltre 25.000 byte viene troncato.

Interrompere un ciclo

• Ciclo autonomo: mentre il ciclo è in attesa della successiva iterazione, premi Esc per interromperlo. Puoi anche interromperlo con Ctrl+C mentre Claude è inattivo, tranne che in una sessione in background a cui ti sei collegato. Un avviso Pending wakeup cancelled conferma che il ciclo non si attiverà di nuovo.
• Ciclo a intervallo fisso: per interrompere un ciclo come /loop 5m, chiedi a Claude di annullarlo, ad esempio cancel the deploy check loop. Esc e Ctrl+C non lo interrompono, né interrompono qualsiasi attività che hai pianificato chiedendo direttamente a Claude. Un ciclo che non annulli termina quando trascorrono sette giorni.

In modalità autonoma, Claude può anche terminare il ciclo da solo una volta che l'attività è completa. Claude chiama lo strumento ScheduleWakeup con stop: true, che annulla il risveglio in sospeso immediatamente. Se un'iterazione termina senza ripianificare o interrompere, Claude Code pianifica un risveglio di fallback circa 20 minuti dopo e termina il ciclo quando quell'iterazione non ripianifica nemmeno.

Scollegarsi senza interrompere un ciclo

Quando sei collegato a una sessione in background e Claude è inattivo, premi Ctrl+C due volte su un prompt vuoto per scollegarti. Un ciclo autonomo in attesa della successiva iterazione continua a funzionare, e quell'iterazione parte come pianificato. Per interrompere invece il ciclo, premi Esc prima di scollegarti. Scollegarsi con Ctrl+C senza interrompere il ciclo richiede Claude Code v2.1.295 o successivo.

Impostare un promemoria una tantum

Per promemoria una tantum, descrivete quello che volete in linguaggio naturale invece di utilizzare /loop. Claude pianifica un'attività a fuoco singolo che si elimina dopo l'esecuzione.

remind me at 3pm to push the release branch

in 45 minutes, check whether the integration tests passed

Claude fissa l'ora di attivazione a un minuto e un'ora specifici utilizzando un'espressione cron e conferma quando si attiverà.

Gestire le attività pianificate con ambito di sessione

Chiedete a Claude in linguaggio naturale di elencare o annullare le attività, oppure fate riferimento direttamente agli strumenti sottostanti.

what scheduled tasks do I have?

cancel the deploy check job

Questi sono gli strumenti sottostanti che Claude utilizza:

Ogni attività pianificata ha un ID di 8 caratteri che potete passare a CronDelete. Una sessione può contenere fino a 50 attività pianificate contemporaneamente.

Come vengono eseguite le attività pianificate con ambito di sessione

Lo scheduler controlla ogni secondo le attività dovute e le accoda a bassa priorità. Un prompt pianificato si attiva tra i vostri turni, non mentre Claude sta rispondendo. Se Claude è occupato quando un'attività scade, il prompt attende fino al termine del turno corrente.

Tutti i tempi vengono interpretati nel vostro fuso orario locale. Un'espressione cron come 0 9 * * * significa le 9 del mattino ovunque stiate eseguendo Claude Code, non UTC.

Jitter

Un'attività pianificata può essere eseguita in un orario diverso da quello indicato dalla sua pianificazione. Se le attività di ogni sessione venissero eseguite esattamente come pianificato, molte di esse chiamerebbero l'API nello stesso momento, quindi Claude Code sposta l'orario di esecuzione di ogni attività. Le attività ricorrenti vengono eseguite in ritardo, tranne un'attività eseguita ogni cinque minuti, scritta */5 * * * *. Le attività una tantum pianificate allo scoccare dell'ora o della mezz'ora vengono eseguite un po' in anticipo.

Per vedere quando è prevista la prossima esecuzione di un'attività, leggi la riga sotto la chiamata CronCreate di Claude nel tuo terminale. La riga mostra quell'orario dopo la pianificazione, ad esempio next run 10:21 AM. Per controllare di nuovo più tardi, chiedi a Claude di elencare le tue attività e cerca next run nelle righe sotto la chiamata CronList. Gli orari della prossima esecuzione in queste righe richiedono Claude Code v2.1.299 o versioni successive.

Quanto in ritardo viene eseguita un'attività ricorrente

A meno che non venga eseguita ogni cinque minuti, un'attività ricorrente avvia ogni esecuzione in ritardo fino alla metà dell'intervallo che la separa dall'esecuzione successiva, e al massimo di 30 minuti. La tua attività rientra in uno di questi tre casi:

• Esecuzioni a intervalli regolari: un'attività con intervalli uguali, ad esempio ogni ora, ogni giorno o ogni 10 minuti, viene eseguita ogni volta con lo stesso numero di minuti di ritardo, anche quando la sessione è inattiva.
• Esecuzioni a intervalli irregolari: un'attività con intervalli diversi, ad esempio una pianificata per :00 e :15 ogni ora, può essere eseguita con un numero di minuti di ritardo diverso in ciascuna esecuzione.
• Ogni cinque minuti: un'attività scritta */5 * * * * non viene ritardata. Un'esecuzione esattamente cinque minuti dopo l'ultima partirebbe dopo la scadenza di una cache del prompt di cinque minuti, quindi ogni esecuzione parte 15 secondi prima.

Trova la tua pianificazione nella prima colonna di questa tabella per vedere quando parte ciascuna delle sue esecuzioni.

Ad esempio, 7,37 * * * * pianifica un'attività per :07 e :37, che distano 30 minuti, quindi il suo ritardo è compreso tra 0 e 15 minuti. Se il ritardo di questa attività è di 14 minuti, viene eseguita a :21 e :51 ogni ora. Cambiare la pianificazione a un minuto diverso sposta l'orario di esecuzione, e il ritardo viene comunque aggiunto.

Quando un'attività una tantum viene eseguita in anticipo

Un'attività una tantum pianificata per :00 o :30 viene eseguita fino a 90 secondi prima. Claude Code non sposta un'attività una tantum pianificata per qualsiasi altro minuto, quindi quando il timing è importante, pianificala lontano dall'ora e dalla mezz'ora esatte: 3 9 * * * invece di 0 9 * * *.

Scadenza di sette giorni

Le attività ricorrenti scadono automaticamente 7 giorni dopo la creazione. L'attività si attiva un'ultima volta, quindi si elimina. Questo limita il tempo di esecuzione di un ciclo dimenticato. Se hai bisogno che un'attività ricorrente duri più a lungo, annullala e ricreala prima che scada, oppure utilizza le attività pianificate nel cloud o le attività pianificate Desktop per una pianificazione durevole.

Riferimento dell'espressione cron

CronCreate accetta espressioni cron standard a 5 campi: minute hour day-of-month month day-of-week. Tutti i campi supportano caratteri jolly (*), valori singoli (5), step (*/15), intervalli (1-5) e elenchi separati da virgole (1,15,30).

Day-of-week utilizza 0 o 7 per domenica fino a 6 per sabato. La sintassi estesa come L, W, ? e gli alias dei nomi come MON o JAN non sono supportati.

Quando sia day-of-month che day-of-week sono vincolati, una data corrisponde se uno dei campi corrisponde. Questo segue la semantica standard di vixie-cron.

Disabilitare le attività pianificate con ambito di sessione

Impostare CLAUDE_CODE_DISABLE_CRON=1 nel vostro ambiente per disabilitare completamente lo scheduler. Gli strumenti cron e /loop diventano non disponibili e tutte le attività già pianificate smettono di attivarsi. Vedere Variabili di ambiente per l'elenco completo dei flag di disabilitazione.

Limitazioni

La pianificazione con ambito di sessione ha vincoli intrinseci:

• Le attività si attivano solo mentre Claude Code è in esecuzione e inattivo. La chiusura del terminale o l'uscita dalla sessione le interrompe. Mettere in background la sessione trasporta le attività /loop a una sessione in background, che continua a funzionare senza un terminale.
• Nessun recupero per attivazioni perse. Se l'ora pianificata di un'attività passa mentre Claude è occupato in una richiesta a lunga esecuzione, si attiva una sola volta quando Claude diventa inattivo, non una volta per ogni intervallo perso.
• In una sessione in background, un loop auto-regolato si interrompe se il suo prossimo risveglio arriva a scadenza mentre il processo della sessione non è in esecuzione, ad esempio dopo un arresto anomalo. Quando il processo si riavvia, la trascrizione mostra un avviso che il risveglio non verrà eseguito. Per continuare il loop, rispondi alla sessione e chiedi a Claude di mantenerlo in esecuzione.
• Quando riprendi una sessione con claude --resume o claude --continue, Claude Code ripristina le attività pianificate con CronCreate, ad eccezione delle attività ricorrenti che sono scadute e delle attività una tantum la cui ora pianificata è già passata. Un /loop auto-regolato non viene ripristinato, quindi esegui /loop di nuovo per riavviarlo.
• Un'attività ricorrente ripristinata non si attiva per le esecuzioni perse mentre la sessione non era in esecuzione. La sua esecuzione successiva è la prima in scadenza dopo la ripresa, e a quell'esecuzione si applica il jitter.
• Quando riprendi con claude --resume o claude --continue, Claude Code non riavvia i comandi Bash in background e i monitor che erano in esecuzione al termine della sessione. Se ne hai ancora bisogno, chiedi a Claude di avviarli di nuovo.
• Con il recupero dei feature flag disattivato, Claude Code memorizza un'attività che hai chiesto di mantenere tra le sessioni nel file .claude/scheduled_tasks.json del progetto. Quando la cartella .claude o quel file è un collegamento simbolico, Claude Code restituisce un errore invece di pianificare l'attività. Un'attività salvata viene eseguita solo nella cartella del progetto in cui l'hai creata. Se copi il file in un'altra cartella, ad esempio un nuovo worktree, le sessioni lì elencano le attività copiate ma non le eseguono, quindi crea di nuovo l'attività in quella cartella.

Per l'automazione basata su cron che deve essere eseguita senza supervisione:

• Attività pianificate nel cloud: eseguite nel cloud su un programma, tramite chiamata API o su eventi GitHub
• GitHub Actions: utilizzare un trigger schedule in CI
• Attività pianificate Desktop: eseguite localmente sulla vostra macchina