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 (ver El anillo Hoy).

Cuentan los tokens de entrada y salida, y la caché no es gratis. Mediciones comparadas con los porcentajes oficiales que comunica Claude Code (octubre de 2026) indican que las escrituras de caché cuentan claramente para la ventana de 5 horas y las lecturas de caché un poco. Un análisis anterior de los límites observados apuntaba en la dirección contraria. Las nuevas mediciones son más directas. Las cifras del plugin siguen contando solo entrada y salida. Cuando una sesión larga tiene que reconstruir su caché, por ejemplo en una nueva ventana de 5 horas tras una pausa o al cargar un contexto grande por primera vez, la cifra oficial puede ir por delante del plugin. En la práctica: las sesiones largas con mucho contexto gastan la ventana de 5 horas más deprisa por respuesta que las sesiones nuevas y cortas.

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. La estimación semanal a partir de límites alcanzados es la semana más baja que llegó al tope y puede quedar muy por debajo, porque la caché, que el plugin no cuenta, también te lleva al límite. Con el feed de la línea de estado (ver Porcentajes oficiales de tu línea de estado) el plugin usa las cifras oficiales.

El anillo Hoy

No existe un límite diario. Anthropic solo limita la ventana de 5 horas y la semana. El anillo «Hoy» compara lo que has usado hoy con tu propia media por día activo, calculada sobre todos los días que Claude Code conserva (tu ajuste de retención de datos, cleanupPeriodDays).

200 % significa que hoy trabajas el doble de lo habitual, nada más. Un día intenso es un cambio en tu forma de trabajar, no un aviso. Lo cerca que estás de un límite solo lo muestran los anillos de la ventana de 5 horas y de la semana. Por eso, desde la 2.1.0, el anillo se queda en gris neutro.

Porcentajes oficiales de tu línea de estado

Opcional, desde la 2.1.0. Token Usage funciona también sin esto. Claude Code conoce los porcentajes oficiales de tu plan, las cifras que muestra /usage. Dos pequeños scripts del repositorio del plugin los escriben en ~/.claude/ratelimit-log.jsonl. Si ese archivo existe, el plugin ancla sus anillos a ellos. La guía completa (en inglés) está en la carpeta extras de GitHub.

Qué ganas

Requisitos

• Una suscripción Pro o Max con la que Claude Code haya iniciado sesión. Con una clave API no hay porcentajes del plan.
• Node.js, porque los dos scripts son pequeños programas de Node. Compruébalo con node --version. Si falta, instala la versión LTS desde la web de Node.js. Si instalaste Claude Code con el instalador nativo, no trae Node.js.
• Una versión reciente de Claude Code y, para la consulta, la línea de comandos de Claude Code claude.

¿Qué script necesito?

Una línea de estado solo se ejecuta mientras el terminal interactivo de Claude Code está abierto. Los programas que integran Claude Code no la ejecutan, así que allí la línea de estado por sí sola da pocas lecturas o ninguna.

Opción A: script de línea de estado

Copia el script en ~/.claude/ratelimit-statusline.js y añade esta entrada a ~/.claude/settings.json, junto a las claves que ya estén allí:

"statusLine": { "type": "command", "command": "node ~/.claude/ratelimit-statusline.js" }

En Windows usa la ruta completa con barras normales, por ejemplo node C:/Users/<tú>/.claude/ratelimit-statusline.js. Reinicia Claude Code; la línea de estado mostrará 5h 12% | week 34%. ¿Ya usas tu propia línea de estado? Consérvala y añádele la parte de registro de nuestro script.

Opción B: consulta programada

Antes de configurarla: cada ejecución es una petición real, muy pequeña (el prompt ok a Haiku, sin guardar sesión), y cuenta en tu consumo. Si en ese momento no hay ninguna ventana de 5 horas abierta, la petición abre una y tu siguiente ventana empieza a la hora de la consulta. Prográmala para horas en las que trabajas de todos modos; tres veces al día es más que suficiente.

Copia el script en ~/.claude/ratelimit-poll.js y ejecútalo una vez a mano con node ~/.claude/ratelimit-poll.js. Muestra 5h 12% | week 34%. Después prográmalo.

Windows (PowerShell, se ejecuta a las 12:00, 17:00 y 22:00 y recupera las ejecuciones perdidas si el equipo estaba apagado):

$node     = (Get-Command node).Source
$script   = "$env:USERPROFILE\.claude\ratelimit-poll.js"
$action   = New-ScheduledTaskAction -Execute $node -Argument "`"$script`""
$triggers = '12:00','17:00','22:00' | ForEach-Object { New-ScheduledTaskTrigger -Daily -At $_ }
$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable
Register-ScheduledTask -TaskName 'TokenUsageLimitPoll' -Action $action -Trigger $triggers -Settings $settings

macOS y Linux (crontab -e, con las rutas completas de which node y which claude, porque cron se ejecuta con un PATH mínimo):

0 12,17,22 * * * CLAUDE_BIN=/ruta/completa/a/claude /ruta/completa/a/node /Users/<tú>/.claude/ratelimit-poll.js

En Linux la carpeta personal suele ser /home/<tú>. Los errores de las ejecuciones programadas se escriben en ~/.claude/ratelimit-poll-errors.log. Si el script no encuentra la línea de comandos de Claude Code, pon en CLAUDE_BIN su ruta completa.

Comprobar que funciona

• El archivo ~/.claude/ratelimit-log.jsonl existe y recibe líneas nuevas.
• En la barra lateral, la línea bajo los tres anillos termina con «derivado del porcentaje oficial de tu feed de línea de estado». La información emergente del anillo semanal dice lo mismo para el límite semanal.
• Justo después de una lectura, /usage en Claude Code y los anillos del plugin muestran los mismos porcentajes.

Cómo usa el plugin las lecturas

Cada lectura incluye el momento en que se reinicia la ventana de 5 horas actual, así el plugin conoce el inicio real de la ventana. La última lectura de la ventana abierta es la base del anillo de 5 horas; entre dos lecturas se suman tus tokens nuevos al ritmo que tuvieron de verdad tus últimas ventanas. La última lectura de la semana en curso a partir del 10 % fija el límite semanal. Las lecturas por debajo del 10 % son demasiado gruesas, porque las cifras llegan en porcentajes enteros. Si ninguna lectura encaja, el plugin vuelve a sus propias estimaciones, como antes.

Límites conocidos

Entre dos lecturas el plugin solo cuenta entrada y salida. Oficialmente, las escrituras de caché también cuentan para la ventana de 5 horas, así que una reconstrucción de la caché (un chat nuevo, o el primer mensaje tras una pausa larga en una sesión larga) aparece con la siguiente lectura. Solo hay lecturas mientras se muestra una línea de estado o a las horas programadas.

Solución de problemas

Privacidad y desinstalación

Todo se queda en tu equipo. Cada línea contiene una marca de tiempo, los dos porcentajes con sus horas de reinicio y, desde la línea de estado, el ID de sesión y el ID del modelo. El plugin solo lee el archivo y nunca ejecuta los scripts por sí mismo. Para quitarlo, borra la entrada statusLine, la tarea programada (Unregister-ScheduledTask -TaskName 'TokenUsageLimitPoll') o la línea de cron y, si quieres, el archivo de registro. El plugin vuelve entonces a sus propias estimaciones.

Actualizado el 10 de octubre de 2026: la primera versión de esta sección no mencionaba Node.js y solo ofrecía la línea de estado, que no se ejecuta en programas como Obsidian. Ambas cosas están añadidas.

¿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. Hay dos tipos con precios distintos: una escritura de caché de 5 minutos cuesta 1,25× el precio de entrada, una de 1 hora cuesta 2×. En nuestros propios registros, cerca del 90 % de las escrituras de caché de Claude Code con suscripción fueron del tipo de 1 hora, mientras que los subagentes escribían cachés de 5 minutos. Desde la 2.1.0, al pasar el ratón por una fila C.Escritura de la barra lateral se ve el reparto. Las escrituras de caché también cuentan para el límite de 5 horas, ver Qué cuenta para un límite.

C.Lectura — lectura de caché

Cualquier petición posterior que reutilice el mismo contexto en caché cuesta solo una fracción del precio de entrada: 0,1× en la mayoría de los modelos, 0,05× en Opus 5.5 y Sonnet 5.5, 0,025× en Fable 5.1. 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. Fuente: página de precios de Anthropic, octubre de 2026. La versión anterior de esta tabla usaba todavía los precios de Sonnet 4.

Coste y límites se calculan de forma distinta. Los tokens de caché cuestan dinero según su propio precio. Según mediciones recientes también cuentan para el límite: claramente las escrituras de caché, poco las lecturas. 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 fracción del precio (0,1× o menos) 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