Inicio / Cuando algo falla

Un comando bloqueado

Ante un comando de shell congelado, pulsa Ctrl+C, que intenta interrumpir la operación; si no basta, relanza con claude --resume. No añadas a mano un prefijo timeout, porque la herramienta Bash ya lleva un parámetro de plazo que Claude decide por sí mismo, y la mayoría de los comandos que alcanzan su plazo pasan a segundo plano sin detenerse.

Un comando de shell lanzado desde Claude Code puede quedarse congelado: ninguna salida, ningún final. El primer gesto es Ctrl+C, que intenta interrumpir la operación en curso sin cerrar la sesión. Si no basta, cerrar la terminal y volver a lanzar con claude --resume en la misma carpeta recupera toda la conversación, solo se pierde el comando bloqueado.

El plazo no es un reflejo que haya que añadir uno mismo

Una costumbre extendida consiste en encuadrar cada comando arriesgado con un prefijo timeout escrito a mano. La herramienta Bash integrada en Claude Code no funciona así. Ya lleva un parámetro timeout que Claude decide añadir por sí mismo cuando anticipa un comando largo, sin ninguna intervención por parte tuya. Dos variables de entorno acotan este comportamiento: BASH_DEFAULT_TIMEOUT_MS fija el plazo por defecto aplicado a cada comando, BASH_MAX_TIMEOUT_MS fija el tope que Claude no puede superar aunque lo solicite.

# Dos variables de entorno leidas por Claude Code
BASH_DEFAULT_TIMEOUT_MS=120000   # 2 minutos, valor por defecto
BASH_MAX_TIMEOUT_MS=600000       # 10 minutos, tope

El paso automático a segundo plano

Cuando un comando alcanza su plazo sin haber terminado, Claude Code no lo detiene: lo hace pasar por sí mismo a segundo plano y sigue trabajando mientras se ejecuta. Tres familias de comandos escapan a este paso automático y siguen siendo bloqueantes hasta el final: las que empiezan por sleep, las que contienen git, y los comandos compuestos que el analizador de seguridad no sabe interpretar, como una expansión del tipo ${PIPESTATUS[0]}. Para un proceso que sabes que va a ser largo desde el principio, un servidor de desarrollo o una compilación en espera, es mejor pedir explícitamente el parámetro run_in_background en lugar de esperar a que se dispare el timeout.

# Simula un comando largo, sin modificar nada en este equipo
node -e "setTimeout(() => console.log('trabajo terminado'), 5000)"
# Lanzado con run_in_background, devuelve el control de inmediato
# y su salida se relee mas tarde, sin haber bloqueado el hilo de la conversacion

El timeout protege frente a un comando que nunca va a terminar, el paso a segundo plano libera la conversación mientras un comando que sí va a terminar se toma su tiempo. Confundir ambas cosas hace esperar a un chat sin necesidad, o corta un comando que iba a completarse.

Esta misma lógica de reanudación sin pérdida vuelve a aparecer cuando es la sesión entera la que se bloquea en lugar de un solo comando, ver bucles, contexto contaminado y reinicio.

Vigilar una tarea en segundo plano sin esperarla

Claude ya no sondea el archivo de salida de un comando en segundo plano ni duerme mientras se ejecuta. La herramienta Monitor existe también en Bedrock, Vertex y Foundry, donde ahora se bloquean las pausas sleep largas en primer plano. Se aplica un límite de duración a los comandos en segundo plano, pero solo en las sesiones sin supervisión (-p, SDK, CI, nube): una sesión de terminal, de escritorio o de VS Code no lo tiene.

Para volver a una sesión en segundo plano, claude attach <nombre> y claude logs <nombre> aceptan parte del nombre de la sesión en lugar del identificador. La tecla ← envía la sesión a segundo plano: un turno o un comando ! iniciado durante el paso se detiene, en lugar de terminar fuera de la vista.