Claude Code: comandos en segundo plano y límite de 30 minutos

Claude Code detiene un comando en segundo plano después de 30 minutos cuando se ejecuta sin supervisión: al iniciarlo con la opción -p, en una aplicación de Agent SDK, en un trabajo de CI o en una sesión en la nube. Si Claude establece un tiempo para el propio comando, este se ejecutará como máximo durante 2 horas. En cambio, el terminal habitual, la aplicación de escritorio y VS Code no tienen límite desde la versión 2.1.288.

Antes me pasaba todo el día delante de la pantalla: darle un paso al agente, echar un vistazo, hacer una corrección y pedirle que continuara. Fase tras fase. Puede que la máquina escribiera el código, pero era yo quien la dirigía. Ahora escribo un plan, lo divido en fases, dejo la implementación en manos de subagentes durante la noche y me voy. En 8 horas sin mí, Claude recorre el plan: estudia, construye y perfecciona. Por la mañana, dedico más tiempo a aceptar el trabajo que a rehacerlo.

Pero si una ejecución nocturna utiliza -p y se ejecuta de forma programada en un servidor, en CI o en la nube, un servidor de desarrollo y una compilación que estén en segundo plano durarán 30 minutos. Entonces Claude Code los detendrá y el trabajo nocturno se quedará a medias. Explicaré a quién afecta el límite, cómo aumentarlo y qué hacer si un comando ya se ha detenido. Vamos allá.

Para obtener ayuda sobre el uso del servicio, consulta la documentación de Ailoot.

A quién afecta el límite#

Un comando en segundo plano es algo que Claude inicia y deja en ejecución mientras se ocupa de otra cosa. Por ejemplo, un servidor de desarrollo iniciado con npm run dev o una compilación que observa los cambios en los archivos.

La documentación de Claude Code dice:

En otras palabras, el límite se aplica cuando no estás presente: en una ejecución con -p, una aplicación de Agent SDK, un trabajo de CI o una sesión en la nube. No hay límite en el terminal, la aplicación de escritorio o VS Code cuando trabajas tú mismo en la sesión. Se introdujo en la versión 2.1.285 y, antes de la versión 2.1.288, se aplicaba en todas partes.

Cómo saber si te afecta:

• Abriste Claude Code en el terminal o en VS Code, le encargaste una tarea y te fuiste a dormir. No hay límite si la versión es la 2.1.288 o posterior. En las versiones de la 2.1.285 a la 2.1.287 también se aplica en este caso. Expliqué cómo actualizar a la última versión en un artículo aparte.
• Claude Code se inicia con claude -p "task" de forma programada, desde tu propia aplicación de Agent SDK o en CI. El límite se aplica.
• La tarea se ejecuta en una sesión en la nube. El límite se aplica.

Cuando dejo que los agentes trabajen de forma autónoma, escribo en el prompt: «Escribe estas condiciones y los motivos para detenerse en el plan de trabajo. Comprueba que el proceso no dependa de una ventana que voy a cerrar ni del propio ordenador». El límite de 30 minutos es uno de esos motivos.

¿Cuánto tiempo puede ejecutar Claude Code un comando en segundo plano?#

La cuenta atrás empieza cuando el comando pasa a segundo plano. Hay 2 casos.

Claude inicia el comando directamente en segundo plano. Tiene 30 minutos. Si Claude especifica un tiempo al iniciarlo (el parámetro timeout), tiene ese tiempo, pero no más de 2 horas.

El comando no termina mientras Claude espera. Claude espera 2 minutos para un comando habitual. Si no ha terminado, Claude Code no lo detiene, sino que lo pasa a segundo plano. A partir de ese momento, tiene 30 minutos.

Cuando se agota el tiempo, Claude Code detiene el comando e informa a Claude:

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

Si el trabajo está sin terminar, Claude puede volver a ejecutar el comando con un tiempo mayor.

Un último detalle sobre -p. En este tipo de ejecución, los comandos en segundo plano terminan aproximadamente 5 segundos después de la respuesta final de Claude. Un servidor iniciado en una ejecución nocturna con -p solo durará lo mismo que la propia ejecución. El límite de 30 minutos importa cuando esta dura más: Claude inicia un servidor al principio y pasa una hora realizando comprobaciones con él.

Cómo organizar el trabajo nocturno en Claude Code#

Me cansé de dirigir al agente todo el día, así que lo sustituí por un único prompt de orquestación. Lo inicio por la noche y Claude trabaja toda la noche, recorriendo las fases en orden: escribir, comprobar, corregir y hacer los commits por su cuenta.

Grupos de subagentes escriben el código, cada uno con sus propios archivos para no estorbarse. Otro grupo, recién formado, acepta el trabajo: revisión del código, comprobaciones de seguridad y comprobaciones en vivo. Si encuentran un problema, lo corrigen de inmediato y vuelven a ejecutar las comprobaciones. El prompt incluye esta frase: «Si te quedas sin contexto, registra el estado; la siguiente ejecución continuará».

En el ejemplo descrito, a lo largo de 3 días se completaron 8 de las 14 fases de esta manera.

Solo hay 2 cosas que tener en cuenta. El orquestador no piensa por ti: primero escribe un plan detallado con fases y después inicia el turno nocturno. Además, consume buena parte de tu cuota de suscripción, por lo que apenas merece la pena configurarlo para una tarea pequeña. Limita siempre el número de intentos o el agente agotará toda tu cuota de suscripción durante la noche. Expliqué cómo establecer estos límites de gasto en un artículo aparte.

Cómo aumentar el límite#

Opción 1: preguntarle a Claude. Claude elige el tiempo para un comando concreto; tú no lo configuras. Pero puedes escribir en la tarea: «Mantén el servidor de desarrollo en segundo plano durante 2 horas». Así no puedes obtener más de 2 horas.

Opción 2: usar variables en el archivo de configuración. Los valores se expresan en milisegundos. No puedes reducir los límites por debajo de 30 minutos y 2 horas; solo puedes aumentarlos.

• BASH_DEFAULT_TIMEOUT_MS: si se establece por encima de 1800000 (30 minutos), cambia el valor predeterminado de 30 minutos. Se aplica tanto a los comandos que Claude inicia en segundo plano sin especificar un tiempo como a los que pasan a segundo plano después de un tiempo de espera. Si lo estableces por encima de 7200000 (2 horas), también aumenta el máximo.
• BASH_MAX_TIMEOUT_MS: si se establece por encima de 7200000, aumenta el máximo de 2 horas. No cambia el valor predeterminado de 30 minutos: un comando sin tiempo especificado seguirá deteniéndose después de 30 minutos.

BASH_DEFAULT_TIMEOUT_MS tiene un efecto secundario. La misma variable establece cuánto tiempo espera Claude a que termine un comando habitual antes de pasarlo a segundo plano. Si la estableces en 1 hora, Claude esperará 1 hora en vez de 2 minutos. Eso no interfiere con el trabajo nocturno. Durante el día, tardarás más en recibir una respuesta cuando los comandos tarden mucho.

Si no quieres entrar en detalles: si necesitas 3 horas tanto para los comandos habituales como para el máximo, establece BASH_DEFAULT_TIMEOUT_MS en 10800000. Es suficiente; no necesitas la segunda variable.

El archivo de configuración está en la carpeta .claude de tu directorio de inicio: ~/.claude/settings.json en macOS y Linux, y %USERPROFILE%\.claude\settings.json en Windows. Si el archivo no existe, créalo. Un límite de 1 hora se configura así:

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

Si el archivo ya tiene un bloque env, añade allí la línea. Una sesión en ejecución recoge los valores nuevos cuando guardas el archivo. Si eliminas una variable, el cambio solo se aplica la próxima vez que inicies claude.

El archivo tiene que estar en la máquina donde se ejecuta el agente. Para que el agente trabaje durante la noche, el ordenador no debe suspenderse. También puedes ejecutar Claude Code en un servidor remoto y guardar allí la configuración.

Si el comando ya se ha detenido#

No tienes que hacer nada manualmente. Claude Code le dice a Claude por qué se detuvo un comando, así que primero pregúntale qué pasó.

Después, sigue estos pasos:

1. Una ejecución puntual larga, de hasta 2 horas. Pídele a Claude que vuelva a ejecutar el comando con un tiempo mayor.
2. Los comandos suelen necesitar más de 30 minutos. Establece BASH_DEFAULT_TIMEOUT_MS por encima de 1800000 en el archivo de configuración, como en el ejemplo anterior. Si necesitas más de 2 horas, establece también BASH_MAX_TIMEOUT_MS por encima de 7200000 allí.
3. Vuelve a ejecutar el comando. La documentación no garantiza nada sobre un comando que ya estaba en ejecución en segundo plano antes del cambio.
4. Comprueba el resultado de la siguiente ejecución. Si el informe de Claude vuelve a contener la frase «stopped after reaching its background time limit», la configuración no se aplicó a ese comando.

Los subagentes y las rutinas permiten que el agente siga trabajando mientras estás fuera.

Expliqué cómo hacer que un agente trabaje en bucle toda la noche en un artículo aparte. Y aquí explico cómo configurar Claude Code para que no estropee el proyecto durante la noche.

Comprueba en qué paso se detiene tu ejecución nocturna y compara el motivo con los límites anteriores.

Conoce Ailoot.