Claude Code compacta una y otra vez: corta el bucle y salva tu trabajo
Por qué Claude Code compacta tu conversación sin parar — cómo interactúan el umbral del auto compact, la compactación por inactividad de 2.1.299 y las discrepancias de gateway — más la recuperación con resume y checkpoints, el interruptor Idle compaction de /config, CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS y las correcciones de 2.1.301 y 2.1.309, sobre grabaciones reales de pantalla.
La compactación constante de un vistazo
- La compactación es el resumen automático que libera espacio de contexto — Claude Code compacta cuando la conversación se acerca a la ventana del modelo (200K en Sonnet 4.6/Opus 4.6 sin extended context, ~967K por defecto en modelos con ventana de 1M).
- "Sigue compactando" tiene tres causas habituales: una ventana genuinamente llena, la compactación por inactividad añadida en 2.1.299 (una conversación de más de 200K tokens inactiva ~54 minutos se compacta antes de que expire su caché de prompts de una hora) o una discrepancia de gateway/nombre de modelo corregida en 2.1.301.
- Nada de lo ya enviado se pierde: el resumen conserva el código clave y las decisiones, y resume más los checkpoints devuelven el resto — la fila de compactación de una sesión reanudada te dice dónde se guardaron los mensajes anteriores (2.1.301).
- Ajústalo, no lo combatas: /autocompact o la clave autoCompactWindow cambia la ventana, CLAUDE_CODE_AUTO_COMPACT_WINDOW se impone a todo, y "idleCompaction": false (o la fila Idle compaction de /config) desactiva la compactación por inactividad.
- Dos bucles concretos de versión ya tienen correcciones publicadas: la compactación repetida tras un gateway de LLM que anuncia otro modelo (2.1.301) y la compactación repetida tras leer archivos bajo un CLAUDE.md anidado muy grande (2.1.309) — actualiza antes de ajustar nada.
Claude Code: CLAUDE.md, Memory & Session Management
CanalDavid Mahler22:39
Stop Losing Work When You Compact Claude Code
CanalThe Art of Vibe Coding7:28
Model configuration — Claude Code documentation
Docscode.claude.com
Los fotogramas de mecánica vienen del walkthrough de gestión de sesiones de David Mahler — diagramas de contexto animados, la cuadrícula de uso de /context con su fila Autocompact buffer y el diagrama del resumen de compactación. Las diapositivas de umbral y handoff vienen del explicador animado de The Art of Vibe Coding. Los datos están cotejados contra el CHANGELOG de Claude Code (2.1.299, 2.1.301, 2.1.302, 2.1.309) y la documentación oficial de configuración de modelos. Un vídeo de charla a cámara y un fotograma de spinner que ya usaba nuestra guía de reducir tokens quedaron descartados como fuentes.
Los fotogramas del vídeo siguen siendo propiedad de sus creadores y se incrustan aquí como documentación paso a paso, con atribución y enlaces profundos.
Evitar que Claude Code compacte una y otra vez
Paso 1 — Entender qué está haciendo la compactación
- 1
Saber qué es en realidad la compactación
La compactación es un proceso automático que libera espacio de contexto resumiendo los mensajes antiguos mientras conserva el código clave y las decisiones. Claude Code compacta cuando la conversación se acerca a la ventana del modelo — en el límite de 200K en Sonnet 4.6 y Opus 4.6 sin extended context, o por defecto en torno a 967K tokens en modelos con ventana nativa de 1M. Ver "Compacting conversation…" una vez en una sesión larga es el sistema funcionando como está diseñado, no un error.
La diapositiva de definición de compactación: un proceso automático que resume los mensajes antiguos conservando el código clave y las decisiones.Ver en 10:40 - 2
Ver qué está llenando tu ventana
Ejecuta /context antes de cambiar nada. Imprime el modelo, el recuento de tokens frente a la ventana y un desglose por categorías — system prompt, system tools, MCP tools, memory files, Messages, espacio libre y el Autocompact buffer reservado. En la sesión grabada, Messages por sí solo ocupaba 129.9k de 149.1k tokens (65%) con 33k (16.5%) reservados para el buffer, y por eso llegó la compactación: la propia conversación, no un fallo, consumía la ventana.
La cuadrícula de uso de /context al 75%: Messages con 129.9k tokens y el Autocompact buffer de 33k (16.5%) señalados abajo.Ver en 10:20 - 3
Entender cómo se siente un bucle de hinchazón
Cuando se acumulan salidas largas, lecturas de archivos grandes o resultados enormes de herramientas, el bloque Messages desplaza a todo lo demás — las descripciones de skills, las MCP tools y las instrucciones recordadas quedan apretadas antes de que te des cuenta. Ese es el estado en el que cada intercambio posterior dispara otro ciclo de compactación. Si /context muestra Messages dominando mientras las filas útiles de instrucciones se encogen, la solución es adelgazar lo que alimentas a la sesión, no solo reajustar umbrales.
El diagrama del contexto hinchado: un bloque Messages crecido hasta desplazar las descripciones de skills, las MCP tools y las instrucciones recordadas.Ver en 11:26
Paso 2 — Recuperar tu trabajo y reiniciar la ventana
- 4
Recuperar: el resumen conserva las decisiones, resume conserva el historial
Nada de lo ya enviado desaparece. La compactación convierte el bloque Messages en una Conversation Summary mientras las filas CLAUDE.md y Auto Memory siguen en su sitio, y los checkpoints de Claude Code más claude --resume / /resume devuelven el resto. Desde 2.1.301, la fila de compactación de una sesión reanudada también te dice dónde se guardaron los mensajes anteriores en vez de ofrecer un historial que no puede cargar. Si una compactación interrumpió un trabajo que te importaba, reanuda la sesión y lee el resumen antes de volver a explicar nada.
El diagrama de antes y después de la compactación: los Messages se convierten en una Conversation Summary mientras las filas CLAUDE.md y Auto Memory, enmarcadas en rojo, se conservan.Ver en 7:56 - 5
Antes de una compactación grande, escribe el trabajo a disco
Para las sesiones cuyo contexto no puedes permitirte perder, salva el reinicio tú mismo: pide a Claude Code un documento de handoff (o usa un skill de handoff como /handoff-doc) que lea la sesión entera — cada decisión, cada archivo tocado, cada cabo suelto — y lo destile en un único HANDOFF.md estructurado en disco. Tras la compactación o en una sesión nueva, apuntar el siguiente prompt a ese archivo recupera el rumbo más rápido que el resumen solo.
El flujo de handoff: el skill /handoff-doc relee la sesión entera — cada decisión, archivo tocado y cabo suelto — en un único HANDOFF.md estructurado.Ver en 1:00 - 6
Ajusta la ventana del auto compact en vez de temerle
El punto de disparo es ajustable. /autocompact <value> lo fija para el modelo actual y lo guarda en la configuración de usuario; la clave autoCompactWindow (por ejemplo "autoCompactWindow": 200000 en ~/.claude/settings.json) aplica a todos los modelos; --autocompact sobrescribe solo para un arranque; y la variable de entorno CLAUDE_CODE_AUTO_COMPACT_WINDOW se impone a todo, aceptando 100,000–1,000,000 tokens (desde 2.1.304 puedes escribir 200k o 1M). Los valores se limitan a la ventana real del modelo, y /autocompact auto vuelve al valor por defecto ajustado.
La cuenta del umbral: el 20 % de una sesión de Opus de 1M tokens son unos 200,000 tokens — cerca de una hora de trabajo real.Ver en 2:12
Paso 3 — Compactación por inactividad: el comportamiento de 2.1.299
- 7
Reconocer la compactación por inactividad (Claude Code 2.1.299)
Desde 2.1.299 hay un segundo disparador que no tiene nada que ver con una ventana llena: la compactación por inactividad. Una conversación que guarda más de 200K tokens y dejas inactiva unos 54 minutos se compacta antes de que expire su caché de prompts de una hora, de modo que tu siguiente mensaje no reprocese todo el transcript a precio completo. Si Claude Code compacta mientras estabas fuera — el aviso aparece en el transcript al volver — es la funcionalidad, no un bucle.
- 8
Desactivar la compactación por inactividad o bajarle el suelo
Dos interruptores, ambos documentados en el changelog de 2.1.299: pon "idleCompaction": false en settings.json para desactivarla por completo, o ajusta CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS para cambiar el mínimo de 200K tokens por debajo del cual nunca se dispara (ambos requieren v2.1.290 o posterior). Desde 2.1.302 también hay una fila Idle compaction en /config, y los avisos que aparecen tras una compactación por inactividad ahora dicen cómo desactivarla. El disparo exige más de 200K tokens inactivos durante ~54 minutos — a las sesiones cortas nunca las toca.
- 9
Decidir si de verdad la quieres apagada
La compactación por inactividad cambia un coste por otro. Dejada activa, pierdes el transcript exacto al volver pasadas una hora; desactivada, tu siguiente mensaje reprocesa todo el transcript de más de 200K tokens con la caché caducada — más lento y facturado a tarifas de caché fallida. Si tus sesiones son largas pero te ausentas a menudo, bajar CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS suele ser mejor que desactivarla: la compactación ocurre en tus términos y contra un bloque más pequeño.
Paso 4 — Bucles de versión y prevención
- 10
Actualiza antes de ajustar: el bucle de gateway de 2.1.301
Si la compactación de verdad se repite con la ventana llena, comprueba primero tu versión. 2.1.301 corrigió conversaciones "que se compactaban una y otra vez, en un modelo que no elegiste, detrás de un gateway de LLM cuyas respuestas anuncian un modelo distinto al solicitado" — las respuestas del gateway anunciaban el modelo X mientras tú pedías el modelo Y, y cada turno recompactaba. El mismo release arregló la fila de compactación de una sesión reanudada que ofrecía ctrl+o para un historial que no podía cargar. Usuarios de gateway en 2.1.300 o anterior: actualiza antes de tocar cualquier ajuste.
- 11
Adelgaza los CLAUDE.md — el bucle de archivo anidado de 2.1.309
Otro bucle documentado: las sesiones seguían compactando una y otra vez tras leer archivos bajo un CLAUDE.md anidado muy grande — 2.1.309 lo corrigió, y ahora un CLAUDE.md anidado que supere el límite de tamaño carga solo su comienzo. Aun así, audita tus memory files: el CLAUDE.md de nivel de usuario carga en todos los proyectos, los archivos de ámbito de proyecto cargan en el directorio de trabajo, y los archivos a demanda de subdirectorios cargan cuando Claude los visita. Saca de los archivos siempre cargados todo lo que no sea una instrucción universal.
El diagrama de ámbitos de memoria: CLAUDE.md de nivel de usuario para todos los proyectos, archivos de ámbito de proyecto en el directorio de trabajo, y archivos a demanda que Claude carga al visitarlos.Ver en 4:44 - 12
Prevenir el siguiente bucle
Tres hábitos convierten la compactación en un no-evento. Mantén los CLAUDE.md ligeros para que las instrucciones sobrevivan a cada compactación. Deja que la compactación ocurra en el umbral en lugar de posponerla — la calidad de las respuestas degrada a medida que la ventana se llena, y el resumen escrito con un 20% restante es mejor que uno escrito al 95%. Y descarga a archivos el estado que te importe (documentos de handoff, planes, checklists) para que cada reinicio parta de algo mejor que un resumen.
La diapositiva de por qué no esperar: la calidad de las respuestas degrada cuando se cruza el umbral de compactación y el compact se pospone.Ver en 2:20
Compactación por inactividad, 2.1.299 en detalle
La compactación por inactividad es la razón más reciente por la que una sesión "sigue compactando" — y la más fácil de malinterpretar como un bug. El changelog de 2.1.299 la introdujo en el terminal con una justificación explícita, y 2.1.301 más 2.1.302 afinaron los controles en torno a ella. Los datos, verificados contra el changelog:
- 1El disparador: una conversación con más de 200K tokens, inactiva unos 54 minutos — cronometrado para que el compact llegue antes de que expire la caché de prompts de una hora.
- 2La justificación: "so your next message doesn't reprocess it all" — un transcript de más de 200K tokens sin compactar, tras la caducidad de la caché, se reprocesa token a token a tarifas de caché fallida.
- 3El interruptor de apagado: "idleCompaction": false en settings.json — o, desde 2.1.302, la fila Idle compaction de /config.
- 4El mando de ajuste: CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS cambia el mínimo de 200K tokens; las conversaciones por debajo nunca se compactan por inactividad.
- 5El suelo de versión: tanto la variable de entorno como el ajuste requieren Claude Code v2.1.290 o posterior — en builds más antiguos la funcionalidad simplemente no existe, por lo que puede parecer un cambio de comportamiento repentino tras una actualización.
- 6Las protecciones: las sesiones cortas nunca se tocan, el aviso aparece en el transcript al volver, y desde 2.1.302 el propio aviso dice cómo apagar la funcionalidad.
Si compartes sesiones en equipo, recuerda que el ajuste es por máquina: "idleCompaction": false en tu configuración de usuario no viaja con el repo, así que la sesión inactiva de un compañero puede compactarse aunque la tuya nunca lo haga. Para sesiones largas compartidas, la combinación previsible es un CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS bajado más un documento de handoff escrito antes de que nadie se ausente.