Entender el consumo de
tokens en Claude Code

Token Usage es un plugin de Obsidian que lee los registros de sesión de Claude Code y muestra el consumo de tokens en vivo directamente en tu barra lateral. Sin clave de API, sin que ningún dato salga de tu equipo — lee los archivos JSONL que Claude Code escribe localmente en ~/.claude/projects/.

Esta página explica cada término que ves en la barra lateral, en el panel y en los informes — y qué significan realmente las cifras para tus costes.

Estimación empírica de límites — una cifra que Anthropic nunca publica

Anthropic no publica el límite real de tokens que hay detrás de un rate-limit hit — existe en el servidor y permanece invisible, tanto para la ventana anclada de 5 horas como para el tope semanal. Token Usage lo hace visible de forma empírica: cada rate-limit hit detectado en tus propios archivos de sesión se convierte en un dato, y suficientes datos dan una estimación de tus propios límites de sesión y semanal. No es una suposición ni lenguaje de marketing — es una cifra construida a partir de lo que realmente ocurrió en tu cuenta.

Encontrarás la estimación actual en dos sitios: el banner de presupuesto del panel, arriba del todo, y la sección Situación actual de la barra lateral con sus tres anillos (ventana 5 h, hoy, esta semana). La línea bajo los anillos indica la estimación de 5 horas de forma explícita y sobre cuántos límites observados se basa. Ambas superficies leen del mismo cálculo, así que nunca pueden contradecirse.

La estimación no es estática: se vuelve más precisa cuanto más usas Claude Code. Cada nuevo rate-limit hit la afina, de modo que la cifra que ves hoy es más fiable que la de tu primera semana.

La estimación de 5 horas se muestra como una mediana junto con una banda habitual: la mitad central de tus límites observados. El mismo límite rara vez se alcanza con exactamente el mismo total, porque otro uso de Claude que Token Usage no puede ver (por ejemplo claude.ai en el navegador) consume del mismo límite; una sola cifra parecería más precisa de lo que es. Cada límite se mide dentro de su propia ventana anclada de 5 horas, exactamente como cuenta el anillo, así que ambos son directamente comparables. En la barra lateral la banda ocupa su propia línea bajo la estimación; en el panel sustituye al anterior rango mín-máx del banner de presupuesto, y la exportación CSV incluye ambos extremos.

Qué cuenta para un límite

Anthropic aplica dos límites y ninguno más: la ventana de 5 horas y un tope semanal que se reinicia un día y a una hora fijos. No existe un límite diario — por eso el panel «Hoy» no es una cuota, sino una comparación con tu propia media reciente.

Solo cuentan los tokens de entrada y salida. Las lecturas y escrituras de caché son volumen real y se muestran íntegras en sus propias filas, pero no te acercan a ninguno de los dos límites. Esto está medido, no supuesto: para cada límite observado el plugin suma la ventana de varias formas posibles, y entrada + salida es con diferencia la más consistente en el momento en que el trabajo se detiene. Ponderar los tokens de caché por sus proporciones de precio — la suposición evidente — daba una cifra mucho más dispersa.

Ninguno de los dos límites es público. Ambas estimaciones salen de tu propio historial, y por eso el plugin solo puede mostrarlas después de haberte visto alcanzar un límite al menos una vez. Hasta entonces lo dice en lugar de inventarse una cifra.

¿Qué es un token?

Un token es un fragmento pequeño de texto — aproximadamente tres cuartos de palabra. No es exactamente una palabra ni exactamente un carácter.

La frase «Buenos días, ¿qué tal estás hoy?» se divide en unos 8 tokens. Las palabras largas o poco frecuentes pueden costar más tokens; las cortas y habituales suelen compartir uno.

Cada llamada a la API se factura por dos conceptos: cuántos tokens entran y cuántos salen. Eso es todo lo que cuenta para la factura.

Entrada y salida

Entrada = todo lo que envías: tu mensaje, el historial de la conversación y el prompt del sistema. Salida = todo lo que Claude escribe de vuelta.

Los tokens de salida suelen costar entre 3 y 5 veces más que los de entrada. Por eso una respuesta larga pesa mucho más en la factura que una pregunta larga.

C.Escritura — escritura en caché

Cuando Claude procesa por primera vez un contexto largo, puede guardarlo («escribirlo») en una caché de prompts. La escritura en caché cuesta aproximadamente 1,25× la entrada normal — un pequeño sobrecoste por adelantado que desbloquea ahorros posteriores.

C.Lectura — lectura de caché

Cualquier petición posterior que reutilice el mismo contexto en caché se sirve a aproximadamente 0,10× el precio de entrada — unas diez veces más barato que reprocesarlo. Un valor alto de C.Lectura significa que estás trabajando de forma eficiente con el mismo material.

C.Escritura vs C.Lectura — el factor de reutilización

Factor de reutilización = C.Lectura ÷ C.Escritura. Una proporción alta indica concentración profunda: el mismo contexto en muchas peticiones. Una proporción baja indica modo exploratorio, con cambios constantes de contexto.

Ninguno de estos valores es «bueno» o «malo» por sí mismo. Describen formas distintas de trabajar: refactorizar un archivo grande produce factores altos, explorar diez proyectos distintos produce factores bajos.

La ventana de 5 horas

Claude Code aplica una ventana de 5 horas, y está anclada, no es móvil. La ventana se abre con tu primer mensaje y dura exactamente cinco horas; una nueva empieza solo cuando ese plazo ha transcurrido por completo, encadenada en bloques fijos de cinco horas sin importar la pausa entre medias. No son «las últimas cinco horas contadas hacia atrás desde ahora» — y es independiente del reinicio semanal, que sigue su propio calendario sin obligar a que empiece una nueva ventana de 5 horas al mismo tiempo.

El plugin reconstruye esas ventanas reales a partir de tu actividad y suma la que está abierta en este momento, mostrando Entrada, Salida, C.Escritura y C.Lectura en filas separadas. Esto importa justo en el momento en que una ventana se renueva: un cálculo móvil sumaría la cola de la ventana que acaba de cerrarse con la cabeza de la que acaba de abrirse, produciendo una cifra que no pertenece a ninguna de las dos — precisamente cuando más quieres ver que tienes presupuesto nuevo.

Por qué la cuenta atrás lleva una tilde (~)

La cuenta atrás en el pie de la barra lateral dice «La ventana de 5 h de Claude se reinicia en: ~Xh Ym». La tilde es intencionada: señala que es una aproximación, no un valor exacto.

Claude Code escribe los datos de sesión en archivos locales después de completar cada respuesta, no en el instante exacto en que envías tu primer mensaje. Al comenzar una sesión, la primera petición suele ser larga — cargar contexto, leer archivos, pensar. Esa primera respuesta puede tardar entre 10 y 25 minutos en quedar registrada.

Esto significa que la cuenta atrás del plugin puede ir entre 10 y 25 minutos por detrás de la que muestra Claude. Para la hora exacta, consulta la sección de uso del plan en Claude Code o en claude.ai. El valor del plugin es una orientación fiable, pero la indicación de Claude es la fuente autoritativa.

Reinicio semanal

El límite semanal se reinicia un día y a una hora fijos que difieren para cada cuenta. Todo lo relacionado con la semana depende de ello: el anillo semanal, la previsión, el mapa de actividad y la propia estimación semanal.

Normalmente no tienes que configurar nada. Cuando alcanzas un límite semanal, Claude escribe en el mensaje la hora del siguiente reinicio, y el plugin la lee de ahí — los ajustes muestran entonces una marca verde y la fecha del límite del que se tomó el valor. Mientras eso no haya ocurrido al menos una vez, supone domingo a las 18:00 y lo indica.

Puedes fijarlo a mano en Ajustes → Reinicio semanal. Un ajuste manual prevalece: la detección automática no lo sobrescribe, solo lo confirma. Conviene revisarlo tras un cambio de hora si tu reinicio parece haberse desplazado una hora.

Las tres vistas temporales — cómo se relacionan

Son tres cortes independientes de los mismos datos. No están anidados automáticamente, y esa es la fuente de confusión más habitual.

Una sesión de Claude Code puede abarcar varios días. Si empezaste ayer y sigues en ella hoy, «Esta sesión» mostrará más tokens que «Hoy». Es lo esperado: la sesión acumula más allá de los límites del calendario.

Del mismo modo, la ventana de 5 horas no es un subconjunto de «Hoy»: una ventana que se abrió ayer por la noche cruza la medianoche, y todo lo que contiene sigue contando para el mismo límite. Igualmente, ambas pueden ser idénticas — si tu ventana se abrió esta mañana y antes no habías trabajado hoy, las dos cifras muestran lo mismo hasta que la ventana se cierre.

La barra lateral, el mapa de actividad y el calendario

Una barra de iconos a la izquierda cambia entre cuatro páginas. Desde la versión 2.0 este es el único diseño — la antigua vista «Classic» y el ajuste que alternaba entre ambas se han eliminado.

Todo lo que hay en Today es de hoy o de la semana en curso por diseño; lo que abarca más tiempo vive en Analíticas o en el panel. En la cabecera, Dashboard e Report generan archivos, CSV exporta a tu vault y la flecha actualiza de inmediato.

Cada una de las cuatro filas de tokens de Today lleva un marcador compacto — un punto verde cuando el valor está cerca de tu media reciente, una flecha ámbar cuando es claramente más alto. La ventana de comparación sigue tu ajuste de retención de datos de Claude, no un número fijo de días.

Mapa de actividad

La cuadrícula de la página Today cubre tu semana de facturación en curso. Una fila por día natural, una celda cada dos horas, doce celdas al día.

Tiene ocho filas, no siete: una semana que va, por ejemplo, de domingo 18:00 a domingo 17:59 toca ocho fechas del calendario, así que la primera y la última fila son parciales a propósito. Las celdas fuera de la ventana se dibujan solo con contorno — eso es lo que hace visible el límite de tu ciclo en lugar de esconderlo dentro de tramos artificiales de 24 horas.

El color indica el ritmo, no el volumen. Una ventana de 5 horas contiene dos tramos y medio de 2 horas, así que gastar todo el presupuesto de forma uniforme son el 40 % por tramo — el ritmo con el que llegas al muro justo al cerrarse la ventana. El rojo marca ese ritmo o más rápido; los niveles inferiores son un cuarto, la mitad y hasta ese ritmo. El matiz dentro de un nivel indica dónde se sitúa exactamente el valor.

Se mantienen separadas tres clases de vacío: fuera de la ventana (solo contorno), aún no alcanzado (pálido) y realmente sin actividad (relleno). Solo la última dice algo sobre cómo fue tu semana. Junto a la cuadrícula, Días activos cuenta los días de esta semana de facturación con actividad.

Calendario de actividad

La página Calendario muestra los dos últimos meses uno debajo del otro. Dos en vez de uno, porque a principios de mes una sola cuadrícula mostraría apenas un puñado de días útiles y ocultaría justo el arranque que se busca. Las flechas desplazan el par hacia atrás, hasta donde llegue el archivo; el calendario nunca va al futuro.

Cada día pasado lleva un punto de color ponderado respecto a tu media diaria reciente: verde por debajo de la media, ámbar alrededor, rojo en un pico (2× o más). Los días sin actividad no tienen punto. Un clic en cualquier día añade una nota privada — se guarda en los ajustes del plugin, nunca en tus datos de sesión.

Exportar tus datos (CSV)

Tres archivos CSV: el resumen de proyectos, la matriz día por vault y los indicadores clave. Dos caminos para obtenerlos, y acaban en sitios distintos.

Botón CSV en la cabecera de la barra lateral — el plugin escribe los archivos en tu vault, en la carpeta configurada en Ajustes → Carpeta de exportación CSV. El menú indica esa carpeta antes de que hagas clic, así sabes dónde van. Las mismas exportaciones están en la paleta de comandos bajo «Export».

Menú CSV Export del panel — el panel es una página web, así que entrega el archivo al navegador y es el navegador quien decide dónde acaba, normalmente tu carpeta de descargas. Una página web no puede elegir carpeta de destino; es una regla del navegador, no una función que falte.

Ambos caminos producen números en bruto y fechas ISO, listos para calcular en Excel, Sheets o en un script. Todo se genera localmente — sin subidas, sin red, igual que el resto del plugin.

Archivo y datos a largo plazo

Claude Code borra sus propios archivos de sesión automáticamente — 30 días por defecto, o lo que configures en cleanupPeriodDays. Sin una copia en otro sitio, todo lo anterior se pierde definitivamente.

El archivo resuelve esto: cada día que usas Claude Code, el plugin escribe un pequeño archivo de resumen en Token Usage Archive/ dentro de tu vault — solo totales agregados, nunca tus conversaciones. Cada vez que abres Obsidian, revisa todos los días todavía disponibles y rellena los que aún no tienen archivo, incluidos los huecos por haber estado cerrado un tiempo.

El límite honesto: el archivo solo puede guardar lo que todavía existe en el momento en que abres la aplicación. Si Obsidian permanece cerrado más tiempo que tu periodo de retención, los días intermedios desaparecen antes de que el plugin llegue a verlos. No hay forma de evitarlo sin ejecutarse de forma continua. Aumenta la retención si abres Obsidian menos de una vez al día.

Modelos

Haiku, Sonnet, Opus y Fable tienen precios muy distintos. La barra de modelos muestra qué parte de tus tokens de los últimos 7 días corresponde a cada uno. Si Opus domina el gráfico, ahí está la mayor parte de tu gasto.

Sesiones

Cada sesión de un proyecto de Claude Code tiene un ID único. Una sesión equivale a un contexto de conversación continuo. La tabla de sesiones principales del panel ordena las sesiones por volumen total de tokens dentro de tu ventana de lectura configurada.

Control de uso por vault y proyecto

Claude Code registra en cada petición el directorio de trabajo desde el que se ejecutó. A partir de ahí, el plugin agrupa el uso por vault y por subproyecto — útil para facturar a varios clientes o para ver qué área de trabajo consume realmente tu presupuesto.

El panel muestra la vista por vault; la exportación Markdown separada y los archivos CSV añaden el detalle por subproyecto.

Qué se mide (y qué no)

Este plugin lee lo que Claude Code escribe en disco, así que cubre todas las formas de usar Claude Code: en una terminal, dentro de Obsidian, en un editor como VS Code y el modo agente integrado en la aplicación de escritorio de Claude. Todo acaba en los mismos números.

Lo que no puede mostrar es el chat normal — las conversaciones en la aplicación de escritorio de Claude o en claude.ai. Esas nunca escriben recuentos de tokens en tu máquina; la única señal de uso disponible allí es un porcentaje redondeado de tu límite actual, no los recuentos reales sobre los que se construye este plugin.

Así que si un día parece más intenso de lo que sugieren las cifras, esa suele ser la razón: tu uso del chat cuenta para el mismo límite del plan, pero no deja rastro local que medir. Conviene tenerlo en cuenta sobre todo para las estimaciones de límites, que solo pueden derivarse de la parte visible aquí.

Precios de la API (referencia aproximada, USD)

El precio real depende de tu plan y del modelo. Estas cifras muestran por qué un factor de reutilización alto reduce los costes de forma notable.

Coste y límites son dos cosas distintas. Los tokens de caché cuestan dinero pero no te acercan al límite de 5 horas ni al semanal — ver Qué cuenta para un límite.

Por qué se acumulan los costes

Cada petición envía de nuevo el historial completo de la conversación. Cuanto más larga es una sesión, más entrada lleva cada mensaje individual — aunque tú solo escribas una línea. Ese crecimiento es la razón principal por la que las sesiones largas se vuelven caras.

La caché amortigua exactamente este efecto: el contexto repetido se sirve a una décima parte del precio en lugar de volver a procesarse por completo.

Qué dispara los costes

• Sesiones muy largas sin reinicio — el historial crece con cada turno
• Opus para tareas que Sonnet resolvería igual de bien
• Archivos grandes leídos una y otra vez en lugar de una vez con caché
• Cambios frecuentes de contexto, que impiden que la caché rinda

Consejos prácticos

• Empieza una sesión nueva cuando cambies de tema — el historial antiguo ya no aporta nada y se paga en cada turno
• Vigila el factor de reutilización: si cae por debajo de 1×, estás pagando el contexto una y otra vez
• Usa el mapa de actividad para ver en qué tramos de dos horas se concentra tu consumo
• Exporta a CSV antes de facturar a un cliente: los números en bruto son más fáciles de defender que una captura de pantalla

Compatibilidad y actualizaciones de Claude Code

El plugin lee el formato JSONL que Claude Code escribe hoy. Si Anthropic cambia ese formato, el plugin puede quedarse temporalmente sin datos — no se pierde nada, pero las cifras se detienen hasta que llegue una actualización. El archivo diario protege tu historial frente a ese caso.

Sobre este plugin

Token Usage es software libre, desarrollado por Björn-Olaf Lange. Sin clave de API, sin cuenta, sin telemetría. Todo ocurre en tu equipo.

Código fuente, reporte de errores y propuestas: github.com/beolatn/token-usage