Request timed out, el fin de la espera de una herramienta Bash, el cierre del terminal y la reanudación de una sesión pueden parecer el mismo fallo de una tarea larga. No lo son: pertenecen a ciclos de vida distintos y dejan estados diferentes.
La primera pregunta tras una interrupción no es «¿lo repito?», sino «¿qué reloj venció y qué efectos pueden haber ocurrido?». Separa petición, comando, conversación, rollback de archivos y estado duradero antes de elegir retry, resume, rewind, respawn u otro runner.
La petición y Bash tienen tiempos de espera distintos
La referencia oficial de errores fija actualmente API_TIMEOUT_MS en 600000 ms por defecto: diez minutos por petición al modelo. La referencia de variables de entorno separa BASH_DEFAULT_TIMEOUT_MS, con 120000 ms, y BASH_MAX_TIMEOUT_MS, con 600000 ms por defecto.
Un timeout de petición significa que Claude Code no recibió la respuesta del modelo antes del deadline. Un timeout de Bash significa que terminó la espera de esa invocación de herramienta; no describe automáticamente el estado de todos los procesos hijos. El tercer límite es el deadline operativo que tú impones al tiempo, coste y riesgo de la tarea completa.
La documentación relaciona Request timed out con carga elevada o respuestas muy grandes. Dividir el trabajo crea puntos de recuperación más claros que limitarse a ampliar la espera. Ajusta API_TIMEOUT_MS solo si una red lenta o un proxy conocido es el cuello de botella: un valor mayor no crea un checkpoint ni convierte un side effect en idempotente.
Claude Code reintenta automáticamente server errors, overload, request timeouts, 429 temporales y conexiones caídas hasta diez veces por defecto, con exponential backoff. Cuando ya ves el error final, esos reintentos se agotaron. Un bucle exterior sin límite puede duplicar costes o efectos sin recuperar nada.
Decide qué puede cerrarse
| Necesidad | Punto de partida | Límite decisivo |
|---|---|---|
| Claude debe iniciar más turnos hasta cumplir una condición | /goal | Funciona alrededor de una sesión; el evaluador solo ve pruebas del diálogo |
| Test, build o servidor no debe bloquear la conversación | Bash en segundo plano, Ctrl+B, /tasks | El proceso se limpia al salir de Claude Code |
| Una sesión local debe separarse del terminal actual | Background session en agent view | Sigue dependiendo del equipo, red, uso y permisos locales |
| Quieres volver a la misma conversación | --continue, --resume, /resume | Recupera el transcript, no el antiguo proceso Bash |
| Necesitas comprobar algo periódicamente en una sesión abierta | /loop o herramientas cron | La programación pertenece a la sesión y caduca |
| El trabajo debe continuar con el ordenador apagado | Remote session, Routines o CI | El entorno remoto no hereda automáticamente archivos locales sin commit |
La documentación del modo interactivo indica expresamente que los comandos Bash en segundo plano se limpian cuando Claude Code termina. Ctrl+B permite seguir conversando mientras corre un proceso largo; no lo convierte en un servicio permanente.
Convierte el objetivo en una condición comprobable
“Termina la migración” deja demasiadas decisiones implícitas. Para un trabajo de horas, define qué salida demuestra el éxito, qué no puede cambiar y cuándo debe detenerse sin éxito.
text/goal migrar el módulo auth a la nueva API async; terminar cuando npm test -- auth y npm run typecheck devuelvan 0 y no existan llamadas a legacyAuthClient; no cambiar el schema ni la forma de la respuesta pública; detenerse tras 15 turnos o 2 horas y explicar el bloqueo
Según la documentación de /goal, después de cada turno un modelo pequeño separado juzga la condición con lo que Claude ya mostró en la conversación. El evaluador no ejecuta comandos ni lee el repositorio por su cuenta. Por eso Claude debe lanzar la prueba decisiva y dejar su resultado en el transcript.
Un goal activo reaparece al reanudar la misma sesión con --continue o --resume, aunque el tiempo, los turnos y el punto de partida de tokens se reinician. Es una forma de retomar el objetivo, no una afirmación de que el agente trabajó durante la interrupción.
Usa Bash en segundo plano para no bloquear la sesión
Los servidores de desarrollo, tests, builds, Docker o Terraform encajan bien en Background Bash cuando solo necesitas seguir usando la conversación. Pide a Claude que ejecute el comando en segundo plano o pulsa Ctrl+B mientras está activo. Dentro de tmux hay que pulsarlo dos veces porque la primera combinación es el prefijo de tmux.
Claude Code devuelve un task ID y escribe la salida en un archivo que puede leer después. /tasks, también disponible como /bashes, permite revisar, conectar o detener el trabajo actual. Así puedes analizar otro fallo mientras termina la suite completa o modificar la interfaz mientras el servidor permanece activo.
Hay dos fronteras operativas. Salir de Claude Code limpia la tarea. Además, el contrato actual termina un background task si la salida supera 5GB. Un proceso muy verboso necesita logs acotados o rotados; un servicio que debe sobrevivir merece un process manager o runner con ciclo de vida explícito.
Desacopla la sesión cuando el terminal es el problema
Las background sessions de agent view son procesos Claude Code gestionados por un supervisor del usuario, no hijos del terminal actual.
bashclaude agents claude attach <id> claude logs <id> claude stop <id> claude respawn <id>
Una sesión que trabaja, espera entrada o tiene un terminal conectado mantiene su proceso. Cuando una sesión ya terminó y permanece desacoplada alrededor de una hora, el supervisor puede detener el proceso para liberar recursos; el transcript y el estado quedan en disco y una conexión posterior inicia un proceso nuevo desde ese punto.
Esto permite cerrar o reutilizar el terminal, pero el trabajo continúa siendo local. Suspensión, apagado, pérdida de red, agotamiento de uso, autenticación o un permission prompt pueden detenerlo. Si el requisito es seguir con el portátil apagado, esta opción no cumple el ciclo de vida.
Un checkpoint es deshacer local, no una transacción
Claude Code crea un checkpoint por cada prompt del usuario. Pulsa Esc dos veces o ejecuta /rewind para restaurar el código, la conversación, ambos, o resumir una parte del contexto. La documentación de checkpointing explica que estos puntos persisten en una sesión reanudada.
El límite es esencial: rewind sigue las ediciones realizadas con las herramientas de archivos de Claude. No revierte cambios de Bash, ediciones manuales o externas ni cambios de otra sesión concurrente. Tampoco es un rollback de base de datos ni sustituye a Git. En un flujo con migration, code generation o API externa, revisa por separado git diff, archivos generados, base de datos y estado remoto.
Una tarea recuperable necesita dos capas: el checkpoint de prompt para la conversación y las ediciones directas, y un registro duradero del proyecto para unidades completadas, verificación y efectos irreversibles. Marca un hito como terminado solo después de que pase su comprobación.
No confundas /loop con automatización duradera
/loop y las tareas programadas sirven para revisar un deployment, vigilar una PR o consultar una build mientras la sesión está disponible.
text/loop 10m comprueba el integration job; si falla, guarda el último failing step y la siguiente acción mínima que pueda cambiar el diagnóstico
Los prompts programados se ejecutan entre turnos. Una tarea recurrente caduca a los siete días. Los intervalos perdidos no se reproducen uno por uno. Reanudar una conversación puede restaurar schedules no caducados, pero nunca restaura Background Bash ni monitor tasks.
Para otra duración, cambia de runner:
- Desktop scheduled tasks accede a archivos locales, pero el ordenador debe estar encendido.
- Las Remote sessions descritas en Claude Code Desktop corren en infraestructura cloud de Anthropic y siguen si cierras la app o apagas el equipo.
- Routines crea una nueva sesión cloud por horario, API o evento compatible y deja el resultado para revisión.
- CI es apropiado cuando el disparador, logs, secretos y approval gates deben vivir junto al repositorio.
Mover el trabajo a cloud cambia su contexto. Un checkout remoto no contiene por arte de magia el diff sin commit de tu portátil, ni todos los servicios, secretos o MCP locales. Declara branch, entorno y artefactos de entrada. Que un run termine solo demuestra que dejó de ejecutarse; no prueba que el objetivo se cumplió.
Guarda el progreso fuera del contexto del modelo
La gestión de sesiones explica que Claude Code guarda continuamente las conversaciones CLI y permite volver con claude --continue, claude --resume o /resume. Aun así, el transcript no debería ser la única copia del estado.
mdObjetivo y límites - qué debe cambiar y qué está prohibido tocar Hitos verificados - archivo, comando de comprobación y resultado Bloqueo actual - error exacto, reproducción mínima, hipótesis descartadas Siguiente acción - un paso concreto y su condición de parada
El ejemplo de Anthropic sobre Claude de larga duración en computación científica utiliza un progress file, test oracle, reglas explícitas y checkpoints Git. Es una práctica de un entorno HPC, no un requisito universal del producto. La lección reutilizable es que el progreso no debe existir solo en la memoria del modelo.
Si hay trabajo paralelo, separa worktrees y propiedad de archivos. Cuando el proyecto necesita varios workers, la guía adyacente de Claude Code Agent Teams ayuda a decidir la coordinación, pero cada lane sigue necesitando su propio criterio de finalización.
Reduce interrupciones sin eliminar la frontera de seguridad
Una tarea nocturna puede quedarse esperando un permiso. Los modos de permisos permiten ajustar la supervisión. acceptEdits reduce pausas en cambios de archivos; dontAsk ejecuta solo herramientas preaprobadas; Auto mode evita prompts con un classifier adicional, pero es una research preview sujeta a versión, plan, modelo, provider y administración.
bypassPermissions omite toda la capa de permisos. Anthropic lo reserva para contenedores o VM aislados y advierte que no protege contra prompt injection. En una tarea desatendida conviene reducir filesystem, red, credenciales, branch y presupuesto, y detenerse antes de deployment, compra, envío de secretos o acción destructiva.
Si un límite de uso interrumpe la sesión, guarda primero objetivo, diff, última comprobación y siguiente paso. Después separa quota, billing, modelo y context pressure con la guía de límites de Claude Code.
Concilia efectos antes de reintentar
Un error de respuesta no demuestra que se hayan deshecho las acciones del turn. Antes de repetir, comprueba si el archivo esperado ya existe, si un test o build dejó artefactos, si el proceso sigue bajo el owner correcto y si una API externa recibió la operación.
Haz cada unidad idempotente cuando sea posible: si el estado deseado ya existe, debe detectarlo y omitir el trabajo; si el sistema externo acepta una operation key, usa una estable para evitar duplicados. Cuando no sea posible, conserva evidencia suficiente para elegir entre verificar, compensar o reintentar.
StopFailure se dispara cuando un turn termina por un API error. La referencia de Hooks aclara que se ignoran su output y exit code, por lo que sirve para log o alerta, no para reanudar automáticamente el turn fallido. Cualquier recovery loop propio sigue necesitando presupuesto de reintentos y una regla de conciliación.
Al volver, no escribas solo “continúa”. Lee el archivo de tarea, confirma git status, comprueba si el proceso existe, inspecciona el último log y repite la prueba mínima. Una tarea larga es recuperable cuando puedes responder quién ejecuta ahora, dónde vive el estado duradero y qué evidencia cierra el trabajo. Con esas tres respuestas, una caída del terminal deja de ser una pérdida de contexto y se convierte en un procedimiento de recuperación.
