Cómo comprobar qué TTL de caché usa tu Claude Code
· 7 min de lectura
Escribe /usage: desde la versión 2.1.251, la línea Prompt cache (main) dice si tu caché está caliente o fría y con qué TTL. Para confirmarlo, ejecuta claude -p "hello" --output-format json y mira usage.cache_creation: las escrituras de una hora salen en ephemeral_1h_input_tokens y las de cinco minutos en ephemeral_5m_input_tokens. Los subagentes no aparecen en esas lecturas y van a cinco minutos salvo que elijas otro valor.
Configurar el TTL de la caché de prompts es la mitad del trabajo. La otra mitad es comprobar qué está usando tu Claude Code de verdad y decidir con ese dato.
Contexto rápido. La conversación principal (tus turnos, las corridas con -p y el Agent SDK) recibe una hora con suscripción dentro del uso incluido del plan, y cinco minutos con créditos de uso, clave de API o proveedor de nube. Todo lo demás (subagentes, workflows, forks, compactación, títulos de sesión) recibe cinco minutos, salvo unas peticiones auxiliares que Anthropic controla en el servidor.
Qué necesitas antes de empezar
Tu versión, con claude --version. La línea de caché de /usage y el objeto prompt_cache piden la 2.1.251; la causa probable del último fallo, la 2.1.260; el TTL por subagente, la 2.1.248.
Una sesión con al menos una respuesta de la conversación principal: antes, la línea no aparece.
La misma carpeta y la misma terminal donde trabajas, para que las pruebas lean tus ajustes y variables.
Cómo ver qué TTL usa tu conversación principal
Paso 1: lee la línea de /usage
Escribe /usage dentro de la sesión. En el bloque Session aparece una línea que empieza por Prompt cache (main). Este es el ejemplo de la documentación:
Prompt cache (main): 14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago)
Léela por partes:
El porcentaje es la parte de tus tokens de entrada que salió de la caché. Cuanto más alto, mejor.
misses son peticiones que volvieron a procesar lo que la caché ya tenía. Claude Code cuenta un fallo cuando la petición reprocesa más del 5 % y al menos 2.000 tokens de lo que podía leer de caché.
expected rebuild son reconstrucciones que Claude Code provoca al compactar o al limpiar resultados viejos de herramientas. No cuentan como fallo.
warm o cold te dice si la caché sigue dentro de su vida útil, con el TTL en vigor. Si está fría, la línea muestra cuánto tiempo lleva inactiva la sesión.
likely cause aparece cuando Claude Code identifica la causa probable del último fallo, por ejemplo likely cause: tool definitions changed.
Si la línea termina en no prompt caching reported by the API, ninguna respuesta ha informado tokens de caché: o la caché está desactivada, o tu proveedor o gateway no la reporta. Y recuerda que /clear la pone a cero.
Paso 2: confírmalo con la prueba JSON
Ejecuta en la terminal:
claude -p "hello" --output-format json
Busca usage.cache_creation en el resultado (con jq: | jq .usage.cache_creation). Las escrituras de una hora salen en ephemeral_1h_input_tokens y las de cinco minutos en ephemeral_5m_input_tokens: el campo con tokens es tu TTL. Las corridas con -p van en el cubo de la conversación principal, así que la prueba refleja ese cubo.
Paso 3: compara forzando cinco minutos
Repite la prueba con esta variable delante:
FORCE_PROMPT_CACHING_5M=1 claude -p "hello" --output-format json
Esa variable fuerza cinco minutos en los dos cubos y gana a cualquier otro control. Si en el paso 2 tenías tokens en ephemeral_1h_input_tokens y ahora pasan a ephemeral_5m_input_tokens, tu lectura es fiable. La documentación la recomienda justo para depurar y comparar los dos TTL.
Paso 4 (opcional): llévalo a tu status line
Un script de status line recibe los mismos números en el objeto prompt_cache:
warm y ttl (5m o 1h) te dan el estado de un vistazo.
expires_at marca cuándo se enfría la caché, y el script se vuelve a ejecutar al llegar esa hora.
recache_tokens_if_cold dice cuántos tokens reescribirá la siguiente petición si la caché ya se enfrió.
last_miss_cause trae la causa del último fallo con nombres como tools_changed, system_prompt_changed o ttl_expired_5m.
Cómo saber si tus subagentes están en cinco minutos
Las lecturas anteriores no te sirven aquí: la línea de /usage y el objeto prompt_cache no cuentan a los subagentes, y la prueba con -p mide la conversación principal. Un subagente queda fuera del cubo principal, así que va a cinco minutos aunque tengas suscripción, hasta que elijas otro valor. Para saber cuál le aplica, recorre este orden; manda el primero que encuentres:
FORCE_PROMPT_CACHING_5M=1 en tu entorno: cinco minutos.
CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL en tu entorno.
subagentPromptCacheTtl en tus ajustes.
cacheTtl dentro del mapa experimental del frontmatter del subagente.
ENABLE_PROMPT_CACHING_1H=1, que pide una hora para los dos cubos.
Si no aparece nada de lo anterior: cinco minutos.
Para revisar las variables, env | grep -i cach te las muestra todas de una vez.
Si quieres fijar el TTL de un solo subagente, abre su archivo y añade al frontmatter un mapa experimental: con la clave cacheTtl: 1h debajo, sangrada. Tiene tres condiciones: va dentro de experimental y no en el nivel superior, Claude Code solo la lee en archivos de subagente, y la ignora en 1h mientras tu suscripción esté tirando de créditos de uso.
Qué hacer con el resultado
Tienes suscripción y ves 5m. O estás tirando de créditos de uso, que baja la conversación principal a cinco minutos, o algún control lo fuerza (una variable, un ajuste tuyo o los ajustes administrados de tu organización). Para conservar la hora con créditos, elígela tú con promptCacheTtl.
Usas clave de API o proveedor de nube y ves 5m. Es el valor por defecto; no hay nada roto. Si dejas la sesión quieta más de cinco minutos a menudo, promptCacheTtl en 1h le da una hora a la conversación principal.
Ves 1h y trabajas en ráfagas cortas. La hora cobra más caras las escrituras de caché y sale peor en ráfagas que nunca pasan de cinco minutos quietas: pagas el recargo y la vida extra no se usa. Ahí 5m es la opción sensata.
Los fallos vienen de ttl_expired_5m. Tus pausas superan los cinco minutos. Es el caso en que la hora compensa.
Los fallos vienen de tools_changed o system_prompt_changed. El TTL no los arregla: algo cambia tu prefijo, por ejemplo un servidor MCP que se conecta o desconecta cuando sus herramientas van cargadas en el prefijo.
Un subagente trabaja muchos turnos con pausas largas. Es candidato a cacheTtl: 1h; uno que termina en dos minutos, no.
Qué puede salir mal
Versión vieja. Sin la 2.1.251 no ves la línea; sin la 2.1.260, no nombra la causa.
El frontmatter pierde contra tus ajustes. El cacheTtl del subagente va por debajo de CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL y de subagentPromptCacheTtl en el orden de prioridad. Si tienes cualquiera de los dos, el valor del frontmatter no llega a aplicarse.
Probar en otra carpeta u otra terminal. Otra carpeta puede cargar otros ajustes de proyecto, y otra terminal, otras variables de entorno.
Un TTL fijado por tu organización. Los ajustes administrados pueden fijarlo para todo el equipo; FORCE_PROMPT_CACHING_5M=1 pasa por encima si allí pusieron uno más largo.
Un gateway que toca las cabeceras. Con ANTHROPIC_BASE_URL, parte de la petición de una hora viaja en la cabecera anthropic-beta, así que configura tu gateway para que la reenvíe sin cambios.
Preguntas frecuentes
¿Cómo sé si Claude Code usa caché de una hora o de cinco minutos?
Ejecuta claude -p "hello" --output-format json y mira usage.cache_creation en el resultado: las escrituras de una hora aparecen en ephemeral_1h_input_tokens y las de cinco minutos en ephemeral_5m_input_tokens. Dentro de la sesión, la línea Prompt cache (main) de /usage muestra el TTL en vigor desde la versión 2.1.251.
¿La línea Prompt cache (main) de /usage incluye a los subagentes?
No. Solo cubre la conversación principal, igual que el objeto prompt_cache que recibe un script de status line. Los subagentes van a cinco minutos por defecto, incluso con suscripción, hasta que elijas otro valor con subagentPromptCacheTtl, con su variable de entorno o con cacheTtl en el mapa experimental del frontmatter del subagente.
¿Por qué tengo suscripción y la caché dice 5m?
Cuando pasas el uso incluido de tu plan y Claude Code empieza a tirar de créditos de uso, la conversación principal baja a cinco minutos. También puede forzarlo una variable como FORCE_PROMPT_CACHING_5M, un ajuste tuyo o los ajustes administrados de tu organización. Si quieres la hora mientras usas créditos, elígela tú con promptCacheTtl.
¿Para qué sirve FORCE_PROMPT_CACHING_5M?
Fuerza cinco minutos en los dos cubos, la conversación principal y todo lo demás, y va primera en el orden de prioridad. La documentación la recomienda para depurar el comportamiento de la caché, comparar los dos TTL o pasar por encima de un TTL más largo fijado en los ajustes administrados.
¿Cuándo conviene pasar a una hora después de comprobarlo?
Cuando ves fallos repetidos porque la caché de cinco minutos expiró, es decir, cuando tus pausas superan ese tiempo. Si trabajas en ráfagas cortas que nunca pasan de cinco minutos quietas, la hora sale peor: cobra más caras las escrituras de caché y su vida extra no se aprovecha.