TL;DR Abre
/costy busca la líneaPrompt cache (main). Te dice qué porcentaje de tu input sale de caché, cuántos fallos llevas y, desde la v2.1.260, qué los causó. Ya no hace falta montarse un script de statusline para mirarlo a mano.
La sesión se arrastra, el consumo sube y ya sabes que la culpa es de la caché. Ahí se acababa la pista. Tocaba repasar de memoria la lista de cosas que la rompen y adivinar cuál te había tocado esta vez.
Desde la v2.1.251, el bloque Session de /cost trae una línea más que cierra ese hueco. Y /cost no es un comando aparte: es alias de /usage y abre la misma pantalla, como ya contamos aquí.
Esto es lo que sale en mi máquina, sin retocar:
Total cost: $545.08
Total duration (API): 7h 41m 1s
Total duration (wall): 14d 5h 18m
Total code changes: 2322 lines added, 29 lines removed
Usage by model:
claude-opus-5: 865.6k input, 1.4m output, 355.7m cache read, 14.8m cache write ($358.29)
claude-fable-5: 3.8m input, 89.4k output, 0 cache read, 0 cache write ($42.72)
claude-haiku-4-5: 374.0k input, 12.0k output, 0 cache read, 0 cache write, 3 web search ($0.4640)
claude-fable-5-1: 4.9m input, 487.1k output, 89.7m cache read, 2.8m cache write ($143.61)
Prompt cache (main): 20 requests · 95% of input tokens from cache · no misses · warm (1h TTL, last activity 8m 39s ago)
Ese Total cost de 545 dólares no es una factura. Con suscripción, Claude Code lo calcula en local a precio de lista y no se cobra: qué mide de verdad cada medidor.
Cómo se lee la línea
Cuatro partes, y las cuatro hablan solo de la conversación principal. Los subagentes no entran.
20 requests: las peticiones que lleva registradas.95% of input tokens from cache: los tokens servidos de caché sobre el total de entrada de esas peticiones. Es la salud de la caché en un número.no misses: ningún reproceso. Cuando los hay, esta parte pasa a2 misses (last 6m 10s ago, 310.2k tokens re-cached), con la hora del último y lo que costó rehacerlo.warm (1h TTL, last activity 8m 39s ago): la caché sigue viva y le queda casi una hora desde el último movimiento.
Esa tercera parte es la que trae el hallazgo. Desde la v2.1.260 le añade la causa con nombre propio, en la forma likely cause: tool definitions changed (+3/-0). No sale de una heurística vaga: viene de un conjunto cerrado de dieciséis diagnósticos que tienes en la tabla de más abajo.
Y si la caché ya expiró, la cuarta parte pasa a cold, dice cuánto lleva la sesión parada y añade cuántos tokens va a recachear el siguiente turno. Ese número es el tamaño total de tu última petición, así que léelo como lo que es: lo que vuelves a pagar si escribes ahora mismo.
Qué cuenta como fallo y qué no
No todo reproceso se marca. Claude Code cuenta una petición como fallo cuando leyó menos del 95% de lo que podía haber leído de caché y además se dejó 2.000 tokens o más sin leer. Hacen falta las dos condiciones. Por debajo de ese doble umbral no aparece nada.
Hay un caso que lo parece y no lo es. Cuando el propio Claude Code acaba de reescribir la conversación, al compactarla o al vaciar resultados de herramientas antiguos, el reproceso es inevitable y no te lo apunta como fallo tuyo: sale aparte como expected rebuild. Solo aparece si ha pasado alguna vez en la sesión.
Las dos mitades del bloque no miden lo mismo
Vuelve al ejemplo de arriba: catorce días de reloj, 1,4 millones de tokens de salida en Opus 5, y la línea de la caché dice 20 requests. No es un error, y conviene entenderlo antes de sacar conclusiones.
Las dos mitades del bloque se guardan de forma distinta. El coste total, las duraciones, las líneas de código y el desglose por modelo se serializan y vuelven contigo cuando retomas la sesión con --resume. El contador de la caché vive en memoria y no se guarda en ninguna parte, así que empieza de cero en cada proceso nuevo.
Hay una segunda razón para que no cuadren. Usage by model suma todo lo que ha corrido, subagentes incluidos. Prompt cache (main) es solo la conversación principal, que es justo lo que anuncia su nombre.
/clear resetea las dos mitades a la vez, así que la diferencia solo se nota cuando retomas.
Cómo usarlo
1. Abre la pantalla, no la pidas por -p
Con suscripción, claude -p "/cost" imprime las barras del plan y el reparto por skill y por servidor MCP, pero no el bloque Session. Esa ruta sirve para saber qué se está comiendo tu límite, que es otra pregunta. Para esta línea abre /cost dentro de la sesión.
2. Mira el porcentaje, no el coste
Prompt cache (main): 20 requests · 95% of input tokens from cache · no misses · warm (1h TTL, last activity 8m 39s ago)
Por encima del 90% la caché trabaja a tu favor y no hay nada que hacer. Si ese número baja sesión tras sesión con la misma forma de trabajar, algo en tu prefijo cambia a menudo. Para hacerte una idea de qué proporción es normal en una sesión sana, sumé esos contadores en tres sesiones enteras.
3. Si hay fallos, lee la causa en vez de deducirla
Aquí está el cambio real. Antes mirabas dos contadores y repasabas la lista de sospechosos. Ahora la línea te da el nombre, y tú vas directo al arreglo con la tabla de abajo.
Referencia: las dieciséis causas que puede nombrar
| Lo que imprime | Qué lo provocó | Dónde está el arreglo |
|---|---|---|
model changed |
Cambiaste de modelo a mitad de sesión | /model y el modelo por defecto |
effort changed |
Cambiaste el nivel de effort | Ajústalo por modelo una vez |
fast mode toggled |
Encendiste o apagaste el modo rápido | Fast mode y lo que cuesta el toggle |
tool definitions changed (+3/-0) |
Cambió el set de tools cargadas en el prefijo | MCP sin comerte el contexto |
deferred tool loading changed |
Cambió el diferido de tools de MCP | MCP sin comerte el contexto |
system prompt changed (+412 chars) |
Cambió el system prompt, con el delta exacto | Las tres capas del prefijo |
idle past the 1h TTL · idle past the 5m TTL |
Pausa más larga que la vida de la caché | Compacta antes de levantarte |
usage-limit state changed |
Pasaste a usage credits y tu TTL cayó a cinco minutos | El TTL por fila |
cache scope or TTL changed |
Cambió promptCacheTtl o el ámbito de la caché |
El TTL por fila |
auto mode toggled |
Entraste o saliste del modo auto | Decisión tuya, pero ahora sabes lo que cuesta |
earlier messages changed |
Se reescribieron mensajes anteriores de la conversación | Qué sobrevive a /compact |
beta headers changed · extra request fields changed |
Cambió la forma de la petición, no algo que hicieras tú | Nada que tocar |
prompt unchanged, likely server-side |
Nada cambió por tu lado | Nada que tocar |
unknown |
No pudo diagnosticarlo | Mira el resto de la línea |
Los nombres de esa tabla salen del propio binario de la v2.1.270, no de la documentación.
Y si lo quieres delante todo el rato
Esta pantalla hay que abrirla. Si prefieres el número siempre a la vista, Claude Code expone los mismos datos a los scripts de statusline en un objeto prompt_cache, con el recuento de fallos por causa incluido. Ahí se monta en tu propia status line, igual que el porcentaje de límite consumido.
Esto es la pieza que le faltaba al trío de siempre: por qué pagas la conversación entera en cada turno explica de dónde sale el gasto, diez hábitos para ahorrar tokens lo reduce, prompt caching evita pagarlo dos veces, y esta línea te dice si lo estás consiguiendo. Si lo que quieres saber es cuándo te van a cortar, eso son los límites de uso.
Documentación oficial: Prompt cache statistics
Requisitos: la línea Prompt cache (main) necesita Claude Code v2.1.251 o superior, y el likely cause: necesita la v2.1.260. Los recuentos salen de los campos de caché que la API devuelve en cada respuesta, así que según la documentación oficial funcionan con cualquier proveedor y cualquier gateway, aunque yo solo lo he visto con suscripción. El formato del likely cause: está leído del código de la v2.1.270, porque en mi sesión no había ningún fallo que enseñar.