Claude Code: limite di 30 minuti per i comandi in background

Claude Code arresta un comando in background dopo 30 minuti quando viene eseguito senza supervisione: con un avvio tramite il flag -p, un’applicazione Agent SDK, un job CI o una sessione cloud. Se Claude imposta una durata per il comando stesso, questo verrà eseguito per non più di 2 ore; invece, il terminale normale, l’app desktop e VS Code non hanno limiti dalla versione 2.1.288.

Prima passavo tutta la giornata davanti allo schermo: assegnavo un passaggio all’agente, controllavo, facevo una correzione, gli chiedevo di continuare. Fase dopo fase. La macchina magari scriveva il codice, ma ero io a guidarla. Ora scrivo un piano, lo divido in fasi, affido l’implementazione ai subagenti durante la notte e me ne vado. In 8 ore senza di me, Claude porta avanti il piano: studia, costruisce e perfeziona. Al mattino, dedico più tempo ad accettare il lavoro che a rifarlo.

Ma se un’esecuzione notturna usa -p, viene avviata a orari prestabiliti su un server, in CI o nel cloud, un server di sviluppo e una build in background dureranno 30 minuti. Poi Claude Code li arresterà e il lavoro notturno si interromperà a metà. Ti spiego chi è interessato dal limite, come aumentarlo e cosa fare se un comando si è già arrestato. Andiamo.

Per assistenza nell’uso del servizio, consulta la documentazione di Ailoot.

A chi si applica il limite#

Un comando in background è un comando che Claude avvia e lascia in esecuzione mentre si occupa di altro. Per esempio, un server di sviluppo avviato con npm run dev o una build che monitora le modifiche ai file.

La documentazione di Claude Code dice:

In altre parole, il limite si applica quando non sei presente: a un’esecuzione con -p, a un’applicazione Agent SDK, a un job CI o a una sessione cloud. Non ci sono limiti nel terminale, nell’app desktop o in VS Code quando lavori direttamente nella sessione. È stato introdotto nella versione 2.1.285 e si applicava ovunque prima della 2.1.288.

Ecco come capire se ti riguarda:

• Hai aperto Claude Code nel terminale o in VS Code, gli hai assegnato un’attività e sei andato a dormire. Non ci sono limiti se la versione è la 2.1.288 o una successiva. Nelle versioni dalla 2.1.285 alla 2.1.287, il limite si applica anche in questo caso. Ho spiegato come aggiornare all’ultima versione in un articolo separato.
• Claude Code viene avviato con claude -p "task" a orari prestabiliti, dalla tua applicazione Agent SDK o in CI. Il limite si applica.
• L’attività viene eseguita in una sessione cloud. Il limite si applica.

Quando affido agli agenti un lavoro autonomo, inserisco nel prompt: “Scrivi queste condizioni e i motivi di arresto nel piano di lavoro. Controlla che il processo non dipenda da una finestra che chiuderò o dal computer stesso.” Il limite di 30 minuti è uno di quei motivi.

Per quanto tempo viene eseguito un comando in background#

Il conto alla rovescia inizia quando il comando passa in background. Ci sono 2 casi.

Claude avvia subito il comando in background. Ha a disposizione 30 minuti. Se Claude specifica una durata all’avvio (il parametro timeout), il comando ha a disposizione quella durata, ma non più di 2 ore.

Il comando non termina mentre Claude è in attesa. Per un comando normale, Claude attende 2 minuti. Se il comando non è terminato, Claude Code non lo arresta, ma lo sposta in background. Da quel momento, ha a disposizione 30 minuti.

Allo scadere del tempo, Claude Code arresta il comando e comunica a Claude:

Background command "<description>" was stopped after reaching its background time limit

Se il lavoro è incompleto, Claude può eseguire di nuovo il comando con una durata maggiore.

Un altro dettaglio su -p. Con questo tipo di esecuzione, i comandi in background terminano circa 5 secondi dopo la risposta finale di Claude. Un server avviato durante un’esecuzione notturna con -p durerà solo quanto l’esecuzione stessa. Il limite di 30 minuti è rilevante quando l’esecuzione dura più a lungo: Claude avvia un server all’inizio e passa un’ora a eseguire controlli su di esso.

Come organizzare il lavoro notturno in Claude Code#

Mi ero stancato di guidare l’agente tutto il giorno, così ho sostituito quel processo con un unico prompt per l’orchestratore. Lo avvio di sera e Claude lavora tutta la notte, seguendo le fasi in ordine: scrive, controlla, corregge e crea commit da solo.

Gruppi di subagenti scrivono il codice, ciascuno con i propri file, così non si intralciano a vicenda. Un altro gruppo, appena avviato, accetta il lavoro: revisione del codice, controlli di sicurezza e verifiche dal vivo. Se trova un problema, viene risolto subito e i controlli vengono eseguiti di nuovo. Il prompt contiene la frase: “Se esaurisci il contesto, registra lo stato; l’esecuzione successiva continuerà.”

Nell’esempio descritto, in 3 giorni sono state completate in questo modo 8 delle 14 fasi.

Ci sono solo 2 aspetti da tenere a mente. L’orchestratore non pensa al posto tuo: prima scrivi un piano dettagliato con le fasi, poi avvia il turno notturno. Inoltre consuma una parte consistente della tua quota di abbonamento, quindi non ha molto senso configurarlo per un’attività piccola. Limita sempre il numero di tentativi, altrimenti l’agente esaurirà durante la notte tutta la quota del tuo abbonamento. Ho spiegato come impostare questi limiti di spesa in un articolo separato.

Come aumentare il limite#

Opzione 1: chiedilo a Claude. Claude sceglie la durata per un determinato comando; non la imposti tu. Puoi però scrivere nell’attività: “Mantieni il server di sviluppo in background per 2 ore.” In questo modo non puoi superare le 2 ore.

Opzione 2: variabili nel file delle impostazioni. I valori sono espressi in millisecondi. Non puoi abbassare i limiti sotto i 30 minuti e le 2 ore: puoi solo aumentarli.

• BASH_DEFAULT_TIMEOUT_MS se impostata sopra 1800000 (30 minuti), modifica il valore predefinito di 30 minuti. Si applica sia ai comandi che Claude avvia in background senza specificare una durata, sia ai comandi spostati in background dopo un timeout. Se la imposti sopra 7200000 (2 ore), aumenta anche il limite massimo.
• BASH_MAX_TIMEOUT_MS se impostata sopra 7200000, aumenta il limite massimo di 2 ore. Non modifica il valore predefinito di 30 minuti: un comando senza una durata specifica continuerà ad arrestarsi dopo 30 minuti.

BASH_DEFAULT_TIMEOUT_MS ha un effetto collaterale. La stessa variabile determina per quanto tempo Claude attende un comando normale prima di spostarlo in background. Impostala a 1 ora e Claude attenderà 1 ora invece di 2 minuti. Di notte questo non è un problema. Di giorno, invece, dovrai attendere più a lungo una risposta quando i comandi richiedono molto tempo.

Se non vuoi entrare nei dettagli: se ti servono 3 ore sia per i comandi normali sia per il limite massimo, imposta BASH_DEFAULT_TIMEOUT_MS su 10800000. È sufficiente; non ti serve la seconda variabile.

Il file delle impostazioni si trova nella cartella .claude della directory home: ~/.claude/settings.json su macOS e Linux, e %USERPROFILE%\.claude\settings.json su Windows. Se il file non esiste, crealo. Un limite di 1 ora si imposta così:

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "3600000"
  }
}

Se il file contiene già un blocco env, aggiungi la riga al suo interno. Una sessione in esecuzione recepisce i nuovi valori quando salvi il file. La rimozione di una variabile ha effetto solo al successivo avvio di claude.

Il file deve trovarsi sul computer in cui è in esecuzione l’agente. Perché l’agente lavori durante la notte, il computer non deve entrare in modalità sospensione. In alternativa, esegui Claude Code su un server remoto e inserisci lì le impostazioni.

Se il comando si è già arrestato#

Non devi fare nulla manualmente. Claude Code comunica a Claude il motivo per cui un comando si è arrestato, quindi per prima cosa chiedigli semplicemente cosa è successo.

Poi procedi passo dopo passo:

1. Un’esecuzione occasionale lunga fino a 2 ore. Chiedi a Claude di eseguire di nuovo il comando con una durata maggiore.
2. I comandi richiedono regolarmente più di 30 minuti. Nel file delle impostazioni, imposta BASH_DEFAULT_TIMEOUT_MS sopra 1800000, come nell’esempio precedente. Se ti servono più di 2 ore, imposta anche BASH_MAX_TIMEOUT_MS sopra 7200000.
3. Esegui di nuovo il comando. La documentazione non garantisce nulla per un comando che era già in esecuzione in background prima della modifica.
4. Controlla il risultato dell’esecuzione successiva. Se il resoconto di Claude contiene di nuovo la frase “stopped after reaching its background time limit”, l’impostazione non si è applicata a quel comando.

I subagenti e le routine permettono all’agente di continuare a lavorare mentre sei via.

Ho spiegato come far funzionare un agente in un ciclo per tutta la notte in un articolo separato. E qui spiego come configurare Claude Code affinché non danneggi il progetto durante la notte.

Controlla quale passaggio arresta la tua esecuzione notturna e confronta il motivo con i limiti descritti sopra.

Scopri Ailoot.