Idle compaction en Claude Code: qué hace y cómo desactivarla

Dejas una sesión larga de Claude Code una hora, vuelves y aparece un aviso que nunca habías visto: “Compacted while idle, before the prompt cache expired.” Es la idle compaction, o compactación en inactividad, una función que Anthropic lanzó en octubre de 2026 y que ha ido ampliando en casi cada versión desde entonces. Viene activada por defecto, por eso mucha gente se la encuentra antes de leer sobre ella.

En este artículo vemos qué hace, cuándo se ejecuta, cómo ajustarla o desactivarla y qué cambia cuando trabajas con varios agentes a la vez.

Qué cambió y cuándo

Las fechas son las de publicación de cada versión en npm; las descripciones vienen del changelog de Claude Code.

Si la usas, actualiza a la 2.1.318 o posterior por esa última corrección.

Por qué Claude Code compacta mientras no estás

Cada mensaje vuelve a enviar la conversación entera. Lo que lo abarata es la caché de prompts: la API reutiliza lo que ya procesó. Pero la caché caduca tras un rato sin actividad. Si vuelves después, tu siguiente mensaje procesa todo el historial como entrada sin caché, algo lento y caro en una conversación de más de 200K tokens.

Compactar sale más barato con la caché todavía caliente, porque la petición de resumen lee el historial desde la caché. La idle compaction aprovecha esa ventana: poco antes de que caduque la caché de una hora, Claude Code escribe el resumen. Al volver, tu siguiente mensaje parte de ese resumen corto en lugar de reconstruir toda la conversación. La documentación sobre caché de prompts explica el equilibrio en detalle.

Cuándo se ejecuta

Según la referencia de ajustes, una conversación solo entra si cumple todo esto:

• Sesión: una sesión interactiva en la terminal, el panel de chat de la extensión de VS Code o la pestaña Code de la app de escritorio cuando la sesión corre en tu máquina o por SSH.
• Compactación automática (autoCompactEnabled) activada.
• Caché de prompts: la conversación usa el TTL de una hora.
• Tamaño: el contexto ha llegado al umbral, 200.000 tokens por defecto.
• Inactividad: ha pasado más o menos una hora desde la última petición y el ordenador sigue despierto hasta entonces.

La condición de la caché importa más de lo que parece. Claude Code pide por defecto el TTL de una hora solo para la conversación principal en una suscripción de Claude, mientras estés dentro del uso de tu plan. Con clave de API o proveedor cloud el valor por defecto es de cinco minutos, así que la idle compaction no se ejecuta salvo que pongas promptCacheTtl en 1h. Si superas el límite del plan y pasas a créditos de uso, la conversación principal también baja a cinco minutos.

Cómo desactivarla

Elige una opción:

• Archivo de ajustes: añade "idleCompaction": false a ~/.claude/settings.json, o al archivo de ajustes de un proyecto para desactivarla solo en ese repositorio.
• /config: cambia la fila Idle compaction. Se guarda en tus ajustes de usuario y se aplica al momento (v2.1.302 o posterior).
• Variable de entorno: DISABLE_AUTO_COMPACT=1 desactiva la idle compaction junto con la compactación automática. El /compact manual sigue funcionando.

{
  "idleCompaction": false
}

Si /config no muestra la fila, probablemente otra fuente de ajustes define la clave: ajustes gestionados, un archivo del proyecto o --settings. Cámbiala ahí.

Cómo ajustar el umbral

CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS fija el tamaño mínimo de la conversación para que se aplique la idle compaction. Los valores por debajo de 100.000 se suben a 100.000.

Hay un detalle útil. En un modelo con ventana de 200K, la compactación automática actúa antes de que la conversación llegue a 200.000 tokens, así que con el umbral por defecto la idle compaction afecta sobre todo a sesiones de 1M de contexto. Para incluir las de 200K, bájalo:

{
  "env": {
    "CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS": "150000"
  }
}

Qué se conserva tras compactar

Compactar sustituye el historial por un resumen, pero no se pierde todo. El CLAUDE.md de la raíz del proyecto y la memoria automática se vuelven a cargar desde disco, el plan del modo plan regresa y Claude Code vuelve a leer hasta cinco de los archivos que leyó o editó, empezando por los modificados más recientemente. Los comandos y subagentes en segundo plano siguen en marcha. Lo que se va es el detalle: salidas exactas de herramientas, razonamientos largos, el ida y vuelta que llevó a una decisión. Lo explicamos con más calma en nuestra guía de la ventana de contexto de Claude Code.

La regla práctica es sencilla. Si habías terminado una tarea, la idle compaction te ahorra dinero y apenas la notarás. Si paraste a mitad de algo delicado y quieres que Claude recuerde cada paso, desactívala en ese proyecto o vuelve antes de una hora.

Qué significa con varios agentes

La idle compaction se pensó para una persona que deja una sesión. Con varios agentes en paralelo el panorama cambia:

• Cada sesión se juzga por separado. Las sesiones en directorios distintos construyen prefijos de caché distintos, así que los agentes en worktrees de git separados nunca comparten caché. Cada uno que supere el umbral y pase una hora inactivo se compacta por su cuenta.
• Un agente que espera es un agente inactivo. El que terminó su turno y espera tu revisión o tu respuesta a una pregunta cuenta como inactivo. Cuando llegas al cuarto panel después de comer, puede que ya trabaje con un resumen. Para “bien, súbelo” no pasa nada; para “vuelve al enfoque que descartaste antes”, no tanto.
• Los subagentes y compañeros de equipo no son el objetivo. Por defecto están en el grupo de caché de cinco minutos. La idle compaction afecta a tus conversaciones principales.
• Las ejecuciones headless no entran. Las ejecuciones con -p y las sesiones del Agent SDK quedan fuera, así que los pipelines nocturnos basados en ellas se comportan como antes. Para trabajo interactivo de noche, mira cómo ejecutar Claude Code por la noche.
• El portátil tiene que seguir despierto. Si se suspende, pasa la hora sin compactar y vuelves a pagar una relectura sin caché.

Una configuración práctica: deja la idle compaction activada por defecto, desactívala en uno o dos repositorios donde un agente suele esperarte a mitad de tarea y procura responder dentro de la hora a los agentes que te hacen preguntas.

Dónde encaja AgentVera

Hacemos AgentVera, una app de escritorio para macOS, Windows y Linux que ejecuta Claude Code, Codex y otros 16 agentes de programación en paralelo, cada uno en una terminal real con tu propia instalación y tu cuenta. Algunas partes encajan con la idle compaction:

• Ahorro de tokens: la compactación automática viene activada para cada agente con un umbral de 150K tokens, usando el comando de compactación de cada CLI, y cada panel muestra el tamaño de contexto en vivo. Un mensaje a un agente inactivo más de una hora compacta antes una conversación grande, lo que cubre también a agentes sin idle compaction propia.
• Notificaciones: te avisa cuando un agente termina o necesita algo, así menos agentes se quedan esperando más de una hora.
• Presupuestos de tokens y límites de uso: un tope por agente y, en la barra de estado, el uso de 5 horas y semanal de cada cuenta de Claude y Codex.

El plan gratuito incluye hasta 18 agentes, MCP, Git, Docker, SSH y revisión de código. Para una comparativa más amplia, mira las mejores apps para Claude Code y Codex en paralelo.

En resumen

La idle compaction es un ajuste por defecto pequeño con un propósito claro: resumir una conversación larga mientras la caché sigue caliente para que tu vuelta no cueste una relectura completa sin caché. Necesita una sesión interactiva, la caché de una hora y un contexto suficientemente grande. Puedes bajar el umbral con CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS o desactivarla con "idleCompaction": false o /config. Cuando varios agentes te esperan a la vez, decide por proyecto si basta con un resumen y responde primero a los que necesitan el contexto completo.

Fuentes: changelog de Claude Code, idleCompaction en la referencia de ajustes, How Claude Code uses prompt caching y Explore the context window.