Ir al contenido
Mastering Claude

Inicio / Cuando algo falla

Cuando algo falla7 minApplication

Un comando bloqueado

Un comando de shell que deja de responder se interrumpe con Ctrl+C sin cerrar la sesión, y el plazo que lo hace pasar a segundo plano ya lo fija el propio Claude, no un prefijo que se añade a mano.

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. No es así como funciona realmente la herramienta Bash integrada en Claude Code. Esta 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

La diferencia entre ambas situaciones se reduce a un solo hecho: 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.

Figure 1

De un comando congelado a la reanudación del trabajo

01
Comando lanzado
Claude ejecuta un comando de shell en la herramienta Bash, con un timeout ya elegido para esa llamada.
02
Ya no hay salida
No se muestra nada, el comando parece congelado aunque el plazo todavía no se ha alcanzado.
03
Ctrl+C
El usuario interrumpe la operación en curso sin salir de la sesión de Claude Code.
04
Plazo alcanzado
Si nadie interrumpe, Claude Code hace pasar el comando a segundo plano en cuanto se alcanza BASH_DEFAULT_TIMEOUT_MS o BASH_MAX_TIMEOUT_MS, salvo para sleep, git y los comandos compuestos ilegibles.
05
Trabajo reanudado
La conversación continúa, la salida del comando se relee más tarde sin haber bloqueado el hilo.
La secuencia muestra los dos desenlaces posibles de un comando que deja de responder: la interrupción manual con Ctrl+C, o el paso automático a segundo plano cuando se alcanza el plazo de la herramienta Bash.
Figure 2

Los dos límites del timeout de la herramienta Bash

2minutos
plazo por defecto aplicado a un comando, variable BASH_DEFAULT_TIMEOUT_MS
code.claude.com/docs/en/tools-reference, 2026-09-02
10minutos
tope del plazo que puede alcanzar un comando, variable BASH_MAX_TIMEOUT_MS
code.claude.com/docs/en/tools-reference, 2026-09-02
Estos dos valores los lee directamente Claude Code al arrancar y acotan toda llamada a la herramienta Bash, tanto el plazo por defecto como el tope que Claude no puede superar.
Calíbralo tú mismo

Un desarrollador lanza desde Claude Code un comando que instala dependencias. Tras un minuto, la pantalla sigue mostrando la misma línea, inmóvil desde el lanzamiento. Pulsa Ctrl+C, la línea de comandos vuelve, y relanza el mismo comando con el parámetro run_in_background.

Escribe en una frase lo que esta situación establece, y en una frase lo que no establece.

Lo que hay que recordar
  • Ctrl+C interrumpe un comando bloqueado sin cerrar la sesión, y claude --resume en la misma carpeta recupera la conversación si hay que cerrar la terminal.
  • El parámetro timeout de la herramienta Bash lo elige el propio Claude para cada comando, no es un prefijo que el usuario escriba a mano.
  • BASH_DEFAULT_TIMEOUT_MS fija el plazo por defecto en dos minutos, BASH_MAX_TIMEOUT_MS limita ese plazo a diez minutos.
  • Al superarse el plazo, Claude Code hace pasar el comando a segundo plano en lugar de detenerlo, salvo para sleep, git, y los comandos compuestos no analizables.
  • run_in_background se pide antes de lanzar un proceso reconocido como largo, no después de que bloquee la conversación.
Hazlo ahora

Lanza un comando que sabes que va a ser largo pidiendo explícitamente a Claude que lo pase a segundo plano antes de que bloquee el chat, en lugar de esperar a que parezca congelado para intervenir.

Verificar en la fuente

Cada afirmación datable de esta lección remite aquí al texto público que la respalda. Una fuente que no se abre no prueba nada.