Gardez Votre Mac Éveillé pour les Exécutions Nocturnes d'Agents avec caffeinate

caffeinate est un outil en ligne de commande intégré à macOS qui empêche votre Mac de se mettre en veille pendant l’exécution d’une tâche — et la forme la plus utile est caffeinate -i <votre commande>, qui encapsule un processus, maintient le système éveillé aussi longtemps qu’il s’exécute, et se libère automatiquement dès qu’il se termine. Si vous avez fermé le couvercle de votre ordinateur portable ou que vous vous êtes absenté pour revenir trouver une session Claude Code, Codex ou un long build interrompue, voici la solution native, sans installation. Cet article couvre les options qui comptent, la recette durable pour les exécutions nocturnes, comment vérifier que l’assertion est bien maintenue, et la seule limite que caffeinate ne peut pas franchir.

Ce qu’est caffeinate sur Mac (la réponse en 10 secondes)

caffeinate est un outil en ligne de commande macOS natif qui crée des assertions de gestion de l’alimentation pour modifier le comportement de mise en veille ; il est disponible dans /usr/bin/caffeinate depuis OS X 10.8 (2012), sans installation ni privilèges administrateur. En coulisses, il appelle l’API d’assertion d’alimentation d’IOKit — un mécanisme qui demande dynamiquement un comportement système au gestionnaire d’alimentation — via IOPMAssertionCreateWithName, le même chemin officiel qu’utilisent les applications pour maintenir un Mac éveillé pendant un travail actif.

Le comportement qui importe pour une tâche longue est l’encapsulation. Si un utilitaire est spécifié, caffeinate crée les assertions au nom de cet utilitaire, et ces assertions persistent pendant toute la durée d’exécution de l’utilitaire ; sinon, caffeinate crée les assertions directement, et elles persistent jusqu’à ce que caffeinate se termine. L’exemple canonique de la page de manuel est caffeinate -i make : caffeinate crée un processus fils, exécute « make » dans celui-ci, et maintient une assertion qui empêche la mise en veille sur inactivité aussi longtemps que ce processus est en cours d’exécution.

Les options de caffeinate qui comptent

Sur un ordinateur portable, la seule option qui compte est caffeinate -i : elle empêche le système de se mettre en veille sur inactivité tout en permettant à l’écran de s’éteindre, ce qui est exactement ce dont un agent en arrière-plan ou un build a besoin. Le jeu complet d’options documentées est plus étendu que la plupart des guides ne l’admettent :

Deux détails que d’autres guides traitent incorrectement. Premièrement, l’assertion -s n’est valide que lorsque le système fonctionne sur secteur — sur batterie, elle est silencieusement ignorée, ce qui en fait un mauvais choix par défaut pour un ordinateur portable débranché. Deuxièmement, si l’écran est éteint, -u le rallume et empêche la mise en veille sur inactivité, et si aucun délai d’expiration n’est spécifié avec -t, cette assertion expire par défaut après 5 secondes. Encapsuler une tâche est plus sûr qu’une assertion nue car elle ne peut pas survivre à la tâche : caffeinate -i npm run build empêche la mise en veille pendant le build et se libère dès qu’il se termine.

La recette pour les exécutions nocturnes d’agents

Pour maintenir Claude Code, Codex CLI ou Aider actifs toute la nuit, encapsulez directement la commande de lancement de l’agent et exécutez-la dans un multiplexeur de terminal afin que rien ne dépende de la fenêtre Terminal restant ouverte. Comme l’assertion vit à l’intérieur du processus caffeinate, elle disparaît si Terminal se ferme ou plante — tmux vous offre une véritable durabilité :

# Démarrer une session tmux détachée qui maintient l'assertion pendant toute sa durée de vie
tmux new-session -d -s agent 'caffeinate -i claude'

Si l’agent est déjà en cours d’exécution dans un autre volet, ne le redémarrez pas — liez une nouvelle assertion à son identifiant de processus existant avec -w :

# Trouver le PID, puis maintenir l'assertion jusqu'à ce que ce processus se termine
pgrep -f claude
caffeinate -i -w <pid>

Avant de vous éloigner d’une exécution de 8 heures, vérifiez que l’assertion est bien maintenue. Dans un second volet, exécutez :

pmset -g assertions

Une entrée PreventUserIdleSystemSleep dans cette sortie confirme que macOS ne mettra pas le système en veille sur inactivité pendant l’exécution de votre tâche ; lorsque la commande encapsulée se termine, la ligne disparaît. Ce diagnostic est la différence entre espérer et savoir que votre exécution nocturne est protégée.

caffeinate peut-il maintenir un MacBook éveillé avec le couvercle fermé ?

caffeinate seul ne maintiendra pas un MacBook éveillé avec le couvercle fermé. La fermeture du couvercle déclenche la mise en veille en mode clapet, et une assertion logicielle d’alimentation ne peut pas la contourner sur batterie — point final. C’est la limite qu’aucun outil en ligne de commande de maintien en éveil ne peut franchir, et c’est pourquoi une tâche s’arrête dès que vous fermez l’ordinateur portable et le débranchez.

Le fonctionnement avec le couvercle fermé est pris en charge dans exactement deux cas. Le premier est le mode clapet d’Apple : Apple prend en charge l’utilisation d’un MacBook avec le couvercle fermé en connectant un écran externe, un clavier et une souris, mais la configuration a des exigences strictes — elle ne fonctionne pas sans moniteur externe et peut introduire des compromis thermiques. La configuration recommandée par Apple connecte un écran externe, un adaptateur secteur, ainsi qu’un clavier et une souris ou un trackpad externes. Le second est le bouton « Empêcher la mise en veille automatique lorsque l’écran est éteint » dans Réglages Système → Batterie → Options — mais cela nécessite que l’ordinateur soit connecté à une source d’alimentation, et non alimenté par sa batterie, pour fonctionner comme prévu.

Si vous avez réellement besoin de la batterie et du couvercle fermé — un ordinateur portable dans un sac exécutant un agent — caffeinate n’est pas le bon outil. Amphetamine est conçu pour ce cas : sa documentation indique qu’avec Amphetamine, votre Mac n’a pas besoin d’un écran, d’un clavier, d’une souris ou d’un adaptateur secteur pour utiliser le mode Couvercle Fermé, car il utilise une API publiquement accessible pour désactiver les exigences d’Apple.

Voici le tableau de synthèse complet :

L’arrêter, et les pièges à éviter

Arrêtez caffeinate avec Ctrl+C au premier plan, ou laissez-le se terminer de lui-même lorsque la commande encapsulée se termine — le modèle d’encapsulation est délibérément conçu pour être difficile à laisser tourner par erreur. Les modes d’échec méritent d’être nommés. Un caffeinate nu sans utilitaire encapsulé ni -t s’exécute jusqu’à ce que vous le tuiez ; laisser un Mac éveillé en permanence augmente la consommation de la batterie, élève la température des composants et ajoute des écritures SSD au fil du temps, alors limitez l’assertion à la durée de la tâche. Et comme l’assertion est liée au processus, fermer ou faire planter Terminal la supprime instantanément — c’est tout l’argument pour encapsuler l’agent dans tmux plutôt que de taper caffeinate en espérant que la fenêtre reste ouverte toute la nuit.

Quand aller plus loin

caffeinate est le bon outil lorsque votre Mac est branché sur secteur, ou avec le couvercle ouvert, et que vous souhaitez protéger une tâche nocturne spécifique avec un nettoyage automatique. Lorsque vous avez besoin de la batterie avec le couvercle fermé, passez à Amphetamine et ses contrôles basés sur les sessions. Et lorsqu’un build ou une exécution d’agent est suffisamment intense pour durer plusieurs jours, la meilleure solution est souvent d’arrêter de gérer l’état d’alimentation d’un ordinateur portable et d’exécuter la charge de travail sur une machine distante toujours disponible — une machine qui ne se met jamais en veille car elle n’a pas été conçue pour cela. Pour le cas d’une exécution nocturne sur votre propre Mac, encapsulez la commande, vérifiez l’assertion avec pmset -g assertions, et allez dormir.

FAQ

Quelle est la différence entre caffeinate -i et caffeinate -d ?

L'option -i empêche la mise en veille système sur inactivité tout en permettant à l'écran de s'éteindre, ce qui est ce dont un agent en arrière-plan ou un build a besoin et le bon choix par défaut sur un ordinateur portable. L'option -d empêche la mise en veille de l'écran, le maintenant allumé et gaspillant de l'énergie pour une tâche sans interface. Utilisez -i pour le travail nocturne en terminal et réservez -d uniquement lorsque l'écran lui-même doit rester allumé, comme pour un tableau de bord de surveillance.

caffeinate nécessite-t-il sudo ou des droits administrateur pour s'exécuter ?

Non. caffeinate ne nécessite aucune installation ni privilèges administrateur car il utilise l'API publique d'assertion d'alimentation d'IOKit, le même mécanisme officiel qu'utilisent des applications comme Xcode pour maintenir un Mac éveillé. Tout utilisateur peut l'exécuter directement depuis Terminal. Il est intégré à macOS dans /usr/bin/caffeinate depuis OS X 10.8, donc il n'y a rien à installer et aucune permission élevée à accorder.

Que se passe-t-il avec caffeinate si je ferme la fenêtre Terminal ?

L'assertion disparaît instantanément. Comme l'assertion de gestion de l'alimentation vit à l'intérieur du processus caffeinate, fermer ou faire planter la fenêtre Terminal termine ce processus et supprime l'assertion, permettant au Mac de se mettre en veille sur inactivité. Pour survivre à une fenêtre fermée ou plantée, exécutez la tâche dans tmux avec caffeinate encapsulant la commande à l'intérieur de la session, afin que l'assertion soit liée à un processus détaché qui survit à votre Terminal.

Comment puis-je faire fonctionner caffeinate pendant un nombre d'heures défini ?

Utilisez l'option -t avec un délai d'expiration en secondes. Par exemple, caffeinate -i -t 28800 empêche la mise en veille sur inactivité pendant exactement huit heures puis se termine automatiquement, libérant l'assertion. C'est utile lorsque vous souhaitez une fenêtre temporelle fixe plutôt que de lier l'assertion à la durée de vie d'une commande spécifique. Sans -t ni utilitaire encapsulé, un caffeinate nu s'exécute jusqu'à ce que vous l'arrêtiez manuellement avec Ctrl+C.