TL;DR Auto-compact es Claude Code resumiendo él solo tu conversación cuando el contexto se acerca a su límite, para que la sesión pueda seguir. Ejecuta
/autocompact. Te dice tu ventana y de dónde sale:default for this model,from settingsofrom CLAUDE_CODE_AUTO_COMPACT_WINDOW. Si no es la del modelo y no sabes quién la cambió,/autocompact autola devuelve a su sitio.
Actualización, 8 de noviembre de 2026: El TL;DR abre ahora con qué es auto-compact, que antes solo se explicaba más abajo.
Actualización, 31 de octubre de 2026: Desde la v2.1.304,
CLAUDE_CODE_AUTO_COMPACT_WINDOWacepta500ky1Mcomo el flag, y avisa cuando un valor se sale de 100K a 1M o no es un tamaño. Antes leía500kcomo500y te dejaba en el mínimo de 100K sin decir nada.
La ventana de auto-compact es cuánto puede llenarse el contexto antes de que salte ese resumen. El umbral real es el mínimo entre esa ventana y el contexto máximo de tu modelo, así que subirla por encima del modelo no te da nada. Y si lo que quieres es que compacte por tiempo y no por llenado, eso es la idle compaction: a los 54 minutos de silencio, antes de que caduque la caché.
Lo interesante no es el número. Es que hay cuatro sitios capaces de fijarlo, uno de ellos gana a los otros tres sin decir nada en ninguna parte, y solo existe una pantalla donde ves cuál mandó.
Resultado:
> /autocompact
Auto-compact window for Sonnet 5.5: 200k tokens (from CLAUDE_CODE_AUTO_COMPACT_WINDOW)
Esa coletilla entre paréntesis es todo el tip. Si dice from CLAUDE_CODE_AUTO_COMPACT_WINDOW y tú no pusiste esa variable, alguien decidió por ti: un .zshrc de hace meses, el script de arranque de tu equipo, la imagen de un contenedor.
Cuatro sitios, y uno gana sin avisar
1. Nada. Si no tocas nada, Claude Code usa la ventana que tiene afinada para tu modelo. Aparece como default for this model.
2. El comando /autocompact 500k. Lo guarda en tus settings de usuario bajo el modelo que estás usando, en modelSettings.<modelo>.autoCompactWindow, y lo aplica ya a la sesión actual (antes de la v2.1.288 guardaba una sola ventana para todos los modelos, en la clave autoCompactWindow). Si un scope de mayor prioridad, por ejemplo los managed settings de tu empresa, fija su propia ventana para ese modelo o para todos, el comando guarda tu valor pero la sesión se queda con la del scope, y te lo dice en pantalla. Es la misma jerarquía que ya viste en cuando CLAUDE.md, skills y MCP chocan.
3. El flag --autocompact 500k al arrancar. Pisa tu ajuste guardado durante ese arranque sin modificarlo. Y al revés que el comando, a este no le puede un scope superior: el flag manda aunque los managed settings digan otra cosa.
4. La variable CLAUDE_CODE_AUTO_COMPACT_WINDOW. Mientras esté puesta con un tamaño que entienda, gana al comando, al flag y al ajuste. Y /autocompact deja de cambiar nada: pasa a informarte del override.
Los formatos no son iguales en los cuatro. El comando y el flag aceptan 200000, 500k, 1M y hasta 200 como atajo de doscientos mil, y rechazan lo que se salga de 100K a 1M con un error explícito:
claude --autocompact 50
# error: option '--autocompact <auto|tokens>' argument '50' is invalid.
# It must be 'auto', or between 100k and 1M (e.g. 500k, 200000, or 200 as shorthand)
La variable de entorno era la que menos entendía. Hasta la v2.1.304 solo leía el entero pelado: le pasé banana y Claude Code arrancó sin una sola queja, y 500k lo leía como 500 y lo subía en silencio al mínimo de 100K. Desde la v2.1.304 acepta 500k y 1M como el flag, y avisa cuando un valor no le sirve:
CLAUDE_CODE_AUTO_COMPACT_WINDOW="banana" isn't a usable size, so Claude Code ignores it. Set it to a size from 100k to 1M, such as 200k or 200000, or unset it.
Lo que sigue sin entender es el atajo: 200 a secas son 200 tokens, no doscientos mil, y acaba en el mínimo de 100K, ahora con aviso. Ese es el problema de fondo que queda: la que gana a las demás lee los mismos números de otra manera.
Por qué es mejor que no la decidas tú
Aquí es donde la intuición falla. Uno piensa que bajar la ventana ahorra tokens, porque compacta antes y la conversación pesa menos en cada petición. El propio Claude Code dice lo contrario, con estas palabras dentro de /autocompact:
The auto setting picks a window tuned for your model and is strongly recommended for the best cost and performance.
Y si detecta que la has sobrescrito, por settings o por variable, añade el aviso:
Overriding auto may result in high token usage, especially when resuming long sessions.
Compactar antes significa compactar más veces, y cada compactación es una llamada extra que resume la conversación entera. Al reanudar sesiones largas eso se acumula. Y esa llamada no cuesta siempre lo mismo: depende de si tu caché sigue viva cuando se lanza, que es justo por qué conviene compactar antes de una pausa larga y no al volver. Por eso el valor de este tip no es elegir mejor número: es descubrir que tienes uno puesto sin saberlo. Y si quieres ver en tu propia máquina cuánto te está costando el contexto largo, /usage lo marca como comportamiento y le pone porcentaje: el desglose de qué se come tu límite. Y desde la v2.1.299 también señala el contexto que se carga en cada petición. La excepción es Haiku 5.5: su precio salta a los 100K, y ahí sí conviene fijarle la ventana en 130K.
Si lo que quieres es controlar el momento de la compactación en vez del tamaño de la ventana, la palanca es otra: el porcentaje de umbral con CLAUDE_AUTOCOMPACT_PCT_OVERRIDE, que ya está en el tip del contexto de 1M. Y si lo que te preocupa es qué se pierde al compactar, eso vive en qué sobrevive a un /compact. Y si la compactación no llega a tiempo y te aparece "Prompt is too long", el final del mensaje te dice si /compact lo arregla.
Cómo dejarlo en su sitio
1. Pregunta quién manda
/autocompact
Lee la coletilla del final. Si pone default for this model, no tienes nada que hacer.
2. Si la fuente es una variable de entorno, encuéntrala
env | grep AUTO_COMPACT
Mira también tu .zshrc, tu .bashrc y cualquier script de arranque del proyecto. La variable gana desde donde esté.
3. Devuélvela a la del modelo
/autocompact auto
Ojo: si el override viene de la variable de entorno, el comando te lo dirá pero no podrá cambiarlo. Ahí toca borrar la variable y reabrir la sesión.
Y desde la v2.1.288, /autocompact auto solo devuelve a su sitio el modelo que estás usando: si en otro modelo la etiqueta sigue diciendo from settings, busca una clave autoCompactWindow de primer nivel en tus settings (ahí la guardaba el comando antes de esa versión) y bórrala.
Referencia
| Dónde | Alcance | Formatos que acepta | Prioridad |
|---|---|---|---|
CLAUDE_CODE_AUTO_COMPACT_WINDOW |
Proceso y scripts | 200000, 500k, 1M (200 son 200 tokens) |
Gana a todo lo demás si el valor le sirve |
--autocompact |
Un arranque | 200000, 500k, 1M, 200, auto |
Gana al ajuste y a los managed settings |
/autocompact |
Modelo actual, en esta sesión y las siguientes | 200000, 500k, 1M, 200, auto |
Cede ante un scope superior |
autoCompactWindow en settings |
Todos los modelos, según el scope del archivo | Entero de tokens | La base sobre la que mandan los anteriores |
| Sin configurar | Todo | No aplica | La ventana afinada para tu modelo |
Etiquetas de origen que puede mostrarte el comando: auto, from settings, from CLAUDE_CODE_AUTO_COMPACT_WINDOW, default for this model y default for an unrecognized model, esta última típica de un gateway o un ID de modelo que Claude Code no reconoce. Si la ventana configurada supera el contexto del modelo, añade · capped to X by model.
Docs oficiales: Model configuration, set the auto-compact window
