Timeout en Claude Code: a los dos minutos se salva todo menos git

TL;DR A los dos minutos Claude Code ya no mata tu comando, lo manda al fondo. Salvo git, que no cumple ninguna de las cinco condiciones y sigue muriendo con un SIGTERM. Como git es el único sin red, es el único donde el valor por defecto decide: pon BASH_DEFAULT_TIMEOUT_MS a lo que tarde tu clone más lento.

Le pides a Claude que instale, compile o pase los tests. Tarda. A los dos minutos la cosa se corta y tú lees «ha fallado».

Casi siempre no ha fallado. Sigue vivo, corriendo por detrás. Pero hay un caso donde sí muere, y es justo el que menos te esperas.

El experimento

Dos comandos. Idénticos salvo por un git --version delante, que no hace nada. Los dos con el mismo límite de tiempo, que he bajado a 5 segundos para que la demostración no dure dos minutos.

$ python3 -c "import time; time.sleep(20)"

Command did not complete within its 5s timeout and was moved to the background
(ID: b1s1kxjyl). Output is being written to: .../tasks/b1s1kxjyl.output

$ git --version > /dev/null && python3 -c "import time; time.sleep(20)"

Exit code 143
Command timed out after 5s

Misma carga, mismo límite. El primero se va al fondo y termina. El segundo muere de un SIGTERM, que es lo que significa ese 143.

La única diferencia es que en el segundo aparece la palabra git.

Las cinco condiciones

Para que tu comando se vaya al fondo en vez de morir tienen que cumplirse las cinco:

Cuatro son fontanería. La que te va a morder es la cuarta, porque git es lo que de verdad tarda: un clone de un repo con años encima, un push grande, un git lfs pull.

Cómo dejarlo arreglado

1. Mide tu git más lento

time git clone --depth 1 <tu-repo-mas-grande> /tmp/prueba-timeout

Ese número, con margen, es tu valor.

2. Ponlo en tus settings

En ~/.claude/settings.json:

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "600000"
  }
}

Diez minutos. Se pone una vez y ya no vuelves a pensar en ello.

3. Para un caso suelto, pídelo y ya

No hace falta configurar nada si es una vez: dile a Claude que use un timeout más largo para ese comando concreto. El modelo puede pedir hasta el techo, y con git funciona igual de bien. La variable es para no tener que acordarte cada vez.

Lo que «irse al fondo» no significa

Que se salve no quiere decir que lo tengas resuelto.

El resultado no vuelve solo a la conversación: queda en un archivo que hay que ir a leer, y para ver todo lo que corre en paralelo está el panel /tasks.

Y hay un caso donde el rescate dura poco: cuando el comando pertenece a un subagente síncrono, lo matan en cuanto ese subagente da su respuesta final. En tu sesión principal no pasa, sigue corriendo y te avisan al terminar. Los subagentes tienen más sorpresas de este estilo.

El tercer final

Hay una tercera forma de morir que no tiene nada que ver con el tiempo:

Command killed: output file exceeded <límite>

Tu comando no tardó demasiado, habló demasiado. Un build ruidoso o unos tests verbosos pueden caer por volumen de salida. Ahí la palanca es BASH_MAX_OUTPUT_LENGTH, y la solución elegante es filtrar antes de que Claude lo lea, que es el hábito 6 de los diez para ahorrar tokens.

Referencia

Documentación oficial: Environment variables