Mantén Tu Mac Activo Durante Ejecuciones Nocturnas de Agentes con caffeinate

caffeinate es una herramienta de línea de comandos integrada en macOS que evita que tu Mac entre en modo de suspensión mientras se ejecuta una tarea — y la forma más útil es caffeinate -i <tu comando>, que envuelve un proceso, mantiene el sistema activo durante todo el tiempo que se ejecuta y libera la aserción automáticamente en el momento en que finaliza. Si alguna vez cerraste la tapa de tu portátil o te alejaste y al volver encontraste un trabajo nocturno de Claude Code, Codex o una compilación larga interrumpidos, esta es la solución integrada que no requiere instalación. Este artículo cubre los flags relevantes, la receta definitiva para ejecuciones nocturnas, cómo verificar que la aserción se mantiene activa y el único límite que caffeinate no puede superar.

Qué es caffeinate en Mac (la respuesta en 10 segundos)

caffeinate es una herramienta de línea de comandos oficial de macOS que crea aserciones de gestión de energía para modificar el comportamiento de suspensión; está disponible en /usr/bin/caffeinate desde OS X 10.8 (2012), no requiere instalación ni privilegios de administrador. Internamente, llama a la API de aserciones de energía de IOKit — un mecanismo que solicita dinámicamente un comportamiento del sistema al gestor de energía — mediante IOPMAssertionCreateWithName, la misma vía oficial que utilizan las aplicaciones para mantener un Mac activo durante el trabajo en curso.

El comportamiento relevante para un trabajo de larga duración es el modo envoltorio (wrap). Si se especifica una utilidad, caffeinate crea las aserciones en nombre de dicha utilidad, y estas persisten durante toda su ejecución; de lo contrario, caffeinate crea las aserciones directamente, y estas persisten hasta que caffeinate finaliza. El ejemplo canónico de la página man es caffeinate -i make: caffeinate bifurca un proceso, ejecuta make en él y mantiene una aserción que evita la suspensión por inactividad mientras ese proceso está en ejecución.

Los flags de caffeinate que importan

En un portátil, el único flag relevante es caffeinate -i: evita que el sistema entre en suspensión por inactividad mientras permite que la pantalla se apague, que es exactamente lo que necesita un agente o proceso de compilación en segundo plano. El conjunto completo de flags documentados es más amplio de lo que la mayoría de las guías reconocen:

Hay dos detalles que otras guías suelen pasar por alto. Primero, la aserción -s solo es válida cuando el sistema funciona con alimentación de CA — con batería no hace nada y no emite ningún aviso, por lo que no es la opción predeterminada adecuada para un portátil desenchufado. Segundo, si la pantalla está apagada, -u la enciende y evita la suspensión por inactividad; si no se especifica un tiempo de espera con -t, esa aserción tiene un tiempo de espera predeterminado de 5 segundos. Envolver una tarea es más seguro que una aserción simple, ya que no puede sobrevivir al trabajo: caffeinate -i npm run build evita la suspensión durante la compilación y libera la aserción en el instante en que finaliza.

La receta para ejecuciones nocturnas de agentes

Para mantener Claude Code, Codex CLI o Aider activos durante toda la noche, envuelve directamente el comando de lanzamiento del agente y ejecútalo dentro de un multiplexor de terminal para que nada dependa de que tu ventana de Terminal permanezca abierta. Dado que la aserción vive dentro del proceso caffeinate, muere si Terminal se cierra o falla — tmux proporciona una durabilidad real:

# Inicia una sesión tmux desacoplada que mantiene la aserción durante toda su vida
tmux new-session -d -s agent 'caffeinate -i claude'

Si el agente ya está ejecutándose en otro panel, no lo reinicies — vincula una nueva aserción a su ID de proceso existente con -w:

# Encuentra el PID y luego mantén la aserción hasta que ese proceso finalice
pgrep -f claude
caffeinate -i -w <pid>

Antes de alejarte de una ejecución de 8 horas, verifica que la aserción se mantiene activa. En un segundo panel, ejecuta:

pmset -g assertions

Una entrada PreventUserIdleSystemSleep en esa salida confirma que macOS no entrará en suspensión por inactividad mientras se ejecuta tu trabajo; cuando el comando envuelto finaliza, la línea desaparece. Este diagnóstico es la diferencia entre esperar y saber que tu ejecución nocturna está protegida.

¿Puede caffeinate mantener un MacBook activo con la tapa cerrada?

caffeinate por sí solo no mantendrá un MacBook activo con la tapa cerrada. Cerrar la tapa activa la suspensión en modo almeja (clamshell sleep), y una aserción de software no puede anularla con alimentación de batería — sin excepciones. Este es el límite que ninguna herramienta de línea de comandos para evitar la suspensión puede superar, y es la razón por la que un trabajo muere en el momento en que doblas el portátil y lo desenchufas.

El funcionamiento con tapa cerrada es posible en exactamente dos casos admitidos. El primero es el modo almeja de Apple: Apple admite el uso de un MacBook con la tapa cerrada conectando una pantalla externa, un teclado y un ratón, pero la configuración tiene requisitos estrictos — no funciona sin un monitor externo y puede introducir compromisos térmicos. La configuración recomendada por Apple conecta una pantalla externa, un adaptador de corriente y un teclado y ratón o trackpad externos. El segundo es el interruptor en Configuración del Sistema → Batería → Opciones, “Evitar la suspensión automática cuando la pantalla esté apagada” — pero esto requiere que el equipo esté conectado a una fuente de alimentación, no funcionando con batería, para que funcione según lo previsto.

Si realmente necesitas batería y tapa cerrada — un portátil en una bolsa ejecutando un agente — caffeinate no es la herramienta adecuada. Amphetamine está diseñado para ese caso: su documentación indica que con Amphetamine, tu Mac no necesita pantalla, teclado, ratón ni adaptador de corriente para usar el Modo de Pantalla Cerrada, ya que utiliza una API de acceso público para desactivar los requisitos de Apple.

Aquí tienes el panorama completo en forma de tabla de verdad:

Cómo detenerlo y los problemas a tener en cuenta

Detén caffeinate con Ctrl+C en primer plano, o deja que salga solo cuando el comando envuelto finalice — el patrón de envoltura está diseñado deliberadamente para ser difícil de dejar en ejecución por error. Vale la pena nombrar los posibles fallos. Un caffeinate simple sin utilidad envuelta y sin -t se ejecuta hasta que lo detengas manualmente; mantener cualquier Mac activo de forma continua aumenta el consumo de batería, eleva las temperaturas de los componentes y añade escrituras en el SSD con el tiempo, así que limita la aserción al trabajo en cuestión. Y dado que la aserción está vinculada al proceso, cerrar o que falle la ventana de Terminal la elimina instantáneamente — que es el argumento principal para envolver el agente en tmux en lugar de escribir caffeinate y esperar que la ventana permanezca abierta toda la noche.

Cuándo recurrir a más herramientas

caffeinate es la herramienta adecuada cuando tu Mac está enchufado, o con la tapa abierta, y quieres proteger un trabajo nocturno específico con limpieza automática. Cuando necesites batería y tapa cerrada, delega en Amphetamine y sus controles basados en sesiones. Y cuando una compilación o ejecución de agente es lo suficientemente intensa como para durar días, la solución más limpia suele ser dejar de gestionar el estado de energía de un portátil y ejecutar la carga de trabajo en una máquina remota siempre activa — una máquina que nunca se suspende porque nunca fue diseñada para ello. Para el caso de ejecución nocturna en tu propio Mac, envuelve el comando, verifica la aserción con pmset -g assertions y ve a dormir.

Preguntas Frecuentes

¿Cuál es la diferencia entre caffeinate -i y caffeinate -d?

El flag -i evita la suspensión del sistema por inactividad mientras permite que la pantalla se apague, que es lo que necesita un agente o proceso de compilación en segundo plano y el valor predeterminado correcto en un portátil. El flag -d evita la suspensión de la pantalla, manteniéndola encendida y desperdiciando energía en un trabajo sin interfaz. Usa -i para trabajo nocturno en terminal y reserva -d solo cuando la pantalla en sí deba permanecer encendida, como en un panel de monitorización.

¿caffeinate necesita sudo o permisos de administrador para ejecutarse?

No. caffeinate no requiere instalación ni privilegios de administrador porque utiliza la API pública de aserciones de energía de IOKit, el mismo mecanismo oficial que utilizan aplicaciones como Xcode para mantener un Mac activo. Cualquier usuario puede ejecutarlo directamente desde Terminal. Viene integrado en macOS en /usr/bin/caffeinate desde OS X 10.8, por lo que no hay nada que instalar ni permisos elevados que conceder.

¿Qué le ocurre a caffeinate si cierro la ventana de Terminal?

La aserción muere instantáneamente. Dado que la aserción de gestión de energía vive dentro del proceso caffeinate, cerrar o que falle la ventana de Terminal termina ese proceso y elimina la aserción, permitiendo que el Mac entre en suspensión por inactividad. Para sobrevivir a una ventana cerrada o fallida, ejecuta el trabajo dentro de tmux con caffeinate envolviendo el comando dentro de la sesión, de modo que la aserción esté vinculada a un proceso desacoplado que sobrevive a tu Terminal.

¿Cómo mantengo caffeinate en ejecución solo durante un número determinado de horas?

Usa el flag -t con un tiempo de espera en segundos. Por ejemplo, caffeinate -i -t 28800 evita la suspensión por inactividad durante exactamente ocho horas y luego sale automáticamente, liberando la aserción. Esto es útil cuando quieres una ventana de tiempo fija en lugar de vincular la aserción a la duración de un comando específico. Sin -t ni una utilidad envuelta, un caffeinate simple se ejecuta hasta que lo detengas manualmente con Ctrl+C.