Claude Code : limite de 30 minutes pour les commandes en arrière-plan

Claude Code arrête une commande en arrière-plan après 30 minutes lorsqu’elle s’exécute sans surveillance : un lancement avec l’option -p, une application Agent SDK, une tâche CI ou une session cloud. Si Claude définit lui-même une durée pour la commande, celle-ci s’exécutera pendant 2 heures au maximum, tandis que le terminal ordinaire, l’application de bureau et VS Code n’ont plus de limite depuis la version 2.1.288.

Avant, je restais devant l’écran toute la journée : donner une étape à l’agent, regarder, corriger, lui demander de continuer. Phase après phase. La machine écrit peut-être le code, mais c’était moi qui la pilotais. Maintenant, je rédige un plan, le divise en phases, confie l’implémentation à des sous-agents pendant la nuit et je pars. En 8 heures sans moi, Claude suit le plan : étudie, construit et affine. Le matin, je passe plus de temps à valider le travail qu’à le refaire.

Mais si une exécution nocturne utilise -p, s’exécute selon un calendrier sur un serveur, dans CI ou dans le cloud, un serveur de développement et un build lancés en arrière-plan dureront 30 minutes. Claude Code les arrêtera alors, et le travail nocturne s’interrompra à mi-parcours. Je vais expliquer qui est concerné par la limite, comment l’augmenter et quoi faire si une commande s’est déjà arrêtée. Allons-y.

Pour obtenir de l’aide sur l’utilisation du service, consultez la documentation Ailoot.

Qui est concerné par la limite de 30 minutes de Claude Code ?#

Une commande en arrière-plan est une commande que Claude lance et laisse s’exécuter pendant qu’il s’occupe d’autre chose. Par exemple, un serveur de développement lancé avec npm run dev ou un build qui surveille les modifications des fichiers.

La documentation de Claude Code indique :

Autrement dit, la limite s’applique lorsque tu n’es pas là : pour une exécution avec -p, une application Agent SDK, une tâche CI ou une session cloud. Il n’y a pas de limite dans le terminal, l’application de bureau ou VS Code lorsque tu travailles toi-même dans la session. Elle a été introduite dans la version 2.1.285 et s’appliquait partout avant la version 2.1.288.

Comment savoir si cela te concerne :

• Tu as ouvert Claude Code dans le terminal ou VS Code, lui as donné une tâche, puis tu es allé te coucher. Il n’y a pas de limite si ta version est la 2.1.288 ou une version ultérieure. Dans les versions 2.1.285 à 2.1.287, elle s’applique aussi dans ce cas. J’ai expliqué comment mettre à jour vers la dernière version dans un article séparé.
• Claude Code est lancé avec claude -p "task" selon un calendrier, depuis ta propre application Agent SDK ou dans CI. La limite s’applique.
• La tâche s’exécute dans une session cloud. La limite s’applique.

Quand je demande aux agents de travailler de manière autonome, j’écris dans le prompt : « Inscris ces conditions et les raisons de l’arrêt dans le plan de travail. Vérifie que le processus ne dépend pas d’une fenêtre que je vais fermer ni de l’ordinateur lui-même. » La limite de 30 minutes est l’une de ces raisons.

Combien de temps une commande en arrière-plan s’exécute#

Le compte à rebours commence lorsque la commande passe en arrière-plan. Il y a 2 cas.

Claude lance immédiatement la commande en arrière-plan. Elle dispose de 30 minutes. Si Claude indique une durée au lancement (le paramètre timeout), elle dispose de cette durée, sans dépasser 2 heures.

La commande ne se termine pas pendant que Claude l’attend. Pour une commande ordinaire, Claude attend 2 minutes. Si elle n’est pas terminée, Claude Code ne l’arrête pas : il la déplace en arrière-plan. À partir de ce moment, elle dispose de 30 minutes.

Lorsque le délai est écoulé, Claude Code arrête la commande et indique à Claude :

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

Si le travail n’est pas terminé, Claude peut relancer la commande avec une durée plus longue.

Un dernier point à propos de -p. Avec ce type d’exécution, les commandes en arrière-plan s’arrêtent environ 5 secondes après la réponse finale de Claude. Un serveur lancé lors d’une exécution nocturne avec -p ne fonctionnera que tant que cette exécution est en cours. La limite de 30 minutes compte lorsque l’exécution dure plus longtemps : Claude lance un serveur au début et passe une heure à effectuer des vérifications dessus.

Comment organiser le travail de nuit dans Claude Code#

J’en avais assez de piloter l’agent toute la journée, alors j’ai remplacé cela par un seul prompt d’orchestration. Je le lance le soir, et Claude travaille toute la nuit en suivant les phases dans l’ordre : écrire, vérifier, corriger et effectuer les commits de façon autonome.

Des groupes de sous-agents écrivent le code, chacun travaillant sur ses propres fichiers pour ne pas se gêner. Un autre groupe, renouvelé, valide le travail : revue de code, contrôles de sécurité et vérifications en direct. S’ils trouvent un problème, il est corrigé immédiatement et les vérifications sont relancées. Le prompt contient cette phrase : « Si tu manques de contexte, consigne l’état ; la prochaine exécution continuera. »

Dans l’exemple décrit, 8 phases sur 14 ont été réalisées de cette manière en 3 jours.

Il y a seulement 2 points à garder à l’esprit. L’orchestrateur ne réfléchit pas à ta place : commence par rédiger un plan détaillé avec des phases, puis lance le travail de nuit. Et il consomme une grande partie de ton quota d’abonnement ; cela vaut donc rarement la peine de mettre ce système en place pour une petite tâche. Limite toujours le nombre de tentatives, sinon l’agent épuisera tout ton quota d’abonnement pendant la nuit. J’ai expliqué comment définir ces limites de dépense dans un article séparé.

Comment augmenter la limite#

Option 1 : demander à Claude. Claude choisit la durée d’une commande donnée ; tu ne la définis pas toi-même. Mais tu peux écrire dans la tâche : « Garde le serveur de développement en arrière-plan pendant 2 heures. » Tu ne peux pas dépasser 2 heures de cette façon.

Option 2 : utiliser des variables dans le fichier de paramètres. Les valeurs sont en millisecondes. Tu ne peux pas abaisser les limites sous 30 minutes et 2 heures ; tu peux seulement les augmenter.

• BASH_DEFAULT_TIMEOUT_MS : une valeur supérieure à 1800000 (30 minutes) modifie la valeur par défaut de 30 minutes. Cela s’applique aux commandes que Claude lance en arrière-plan sans préciser de durée, ainsi qu’aux commandes déplacées en arrière-plan après un délai d’attente. Si tu définis une valeur supérieure à 7200000 (2 heures), la durée maximale augmente aussi.
• BASH_MAX_TIMEOUT_MS : une valeur supérieure à 7200000 augmente la durée maximale de 2 heures. Cela ne change pas la valeur par défaut de 30 minutes : une commande sans durée définie s’arrêtera toujours après 30 minutes.

BASH_DEFAULT_TIMEOUT_MS a un effet secondaire. Cette même variable définit la durée pendant laquelle Claude attend la fin d’une commande ordinaire avant de la déplacer en arrière-plan. Si tu la définis sur 1 heure, Claude attendra 1 heure au lieu de 2 minutes. Cela ne gêne pas le travail de nuit. Pendant la journée, tu attendras plus longtemps une réponse lorsque les commandes prennent beaucoup de temps.

Si tu ne veux pas entrer dans les détails : si tu as besoin de 3 heures pour les commandes ordinaires et pour la durée maximale, définis BASH_DEFAULT_TIMEOUT_MS sur 10800000. Cela suffit ; tu n’as pas besoin de la deuxième variable.

Le fichier de paramètres se trouve dans le dossier .claude de ton répertoire personnel : ~/.claude/settings.json sur macOS et Linux, et %USERPROFILE%\.claude\settings.json sur Windows. Si le fichier n’existe pas, crée-le. Une limite d’une heure se configure ainsi :

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

Si le fichier contient déjà un bloc env, ajoute la ligne à ce bloc. Une session en cours prend en compte les nouvelles valeurs lorsque tu enregistres le fichier. La suppression d’une variable ne prend effet qu’au prochain démarrage de claude.

Le fichier doit se trouver sur la machine où l’agent s’exécute. Pour que l’agent puisse travailler pendant la nuit, l’ordinateur ne doit pas se mettre en veille. Autre possibilité : exécuter Claude Code sur un serveur distant et y placer les paramètres.

Si la commande s’est déjà arrêtée#

Tu n’as rien à faire manuellement. Claude Code indique à Claude pourquoi une commande s’est arrêtée ; demande-lui donc simplement ce qui s’est passé.

Procède ensuite étape par étape :

1. Une exécution ponctuelle de longue durée, jusqu’à 2 heures. Demande à Claude de relancer la commande avec une durée plus longue.
2. Les commandes ont régulièrement besoin de plus de 30 minutes. Définis BASH_DEFAULT_TIMEOUT_MS sur une valeur supérieure à 1800000 dans le fichier de paramètres, comme dans l’exemple ci-dessus. Si tu as besoin de plus de 2 heures, définis aussi BASH_MAX_TIMEOUT_MS sur une valeur supérieure à 7200000 dans ce fichier.
3. Relance la commande. La documentation ne garantit rien pour une commande qui s’exécutait déjà en arrière-plan avant la modification.
4. Vérifie le résultat de l’exécution suivante. Si le rapport de Claude contient à nouveau la phrase « stopped after reaching its background time limit », le paramètre ne s’est pas appliqué à cette commande.

Les sous-agents et les routines permettent à l’agent de continuer à travailler pendant ton absence.

J’ai expliqué comment faire fonctionner un agent en boucle toute la nuit dans un article séparé. Et ici, j’explique comment configurer Claude Code pour qu’il ne casse pas le projet pendant la nuit.

Vérifie à quelle étape ton exécution nocturne s’arrête et compare la raison avec les limites ci-dessus.

Découvre Ailoot.