Docs y manual  ·  Token Usage Plugin

Entender el consumo de
tokens en Claude Code

Token Usage es un plugin de la comunidad 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 cuenta, ningún dato sale de tu equipo: solo lee los archivos JSONL que Claude Code ya escribe en local. Esta única página es a la vez el glosario y el manual completo: instalación, cada término de la barra lateral y del panel, qué lee el plugin y qué no, y qué significan las cifras para tus costes.

Primeros pasos#

Instalar. En Obsidian: Ajustes → Plugins de la comunidad → Explorar → busca «Token Usage» → Instalar → Activar. Esa es toda la configuración: ninguna cuenta que crear, ninguna clave de API que pegar, ningún servicio externo. Funciona igual en Windows, macOS y Linux; el único detalle propio de una plataforma (dónde guarda sus sesiones el modo agente de la app de escritorio de Claude) está en Fuentes de datos y transparencia.

Abrirlo. Haz clic en el icono de gráfico de la cinta izquierda o ejecuta «Open Token Usage» desde la paleta de comandos (Ctrl/Cmd+P). Ambos abren la vista en la barra lateral derecha, donde se queda como cualquier otro panel de Obsidian.

¿«Todavía no hay datos»? Es normal tras una instalación nueva si Claude Code aún no ha escrito nada en el periodo de lectura actual. Empieza o continúa una sesión de Claude Code en cualquier sitio, en un terminal, un editor u Obsidian: la barra lateral la detecta por sí sola mediante un vigilante de archivos, a más tardar en 30 segundos, con una consulta periódica como red de seguridad.

No hace falta configurar nada para obtener cifras útiles. La barra lateral funciona de inmediato: a la izquierda, una barra de iconos con cuatro páginas, Resumen, Calendario, Analíticas y Ajustes, ver más abajo. Desde la 2.0 solo existe esta disposición; la antigua vista «Classic» y el ajuste para cambiar entre ambas han desaparecido.

Comandos disponibles desde el primer día (paleta de comandos, los nombres de los comandos están en inglés):

ComandoQué hace
Open Token UsageAbre la vista de la barra lateral o la trae al frente
Create Token Usage reportEscribe un informe en Markdown en tu vault
Open Token Usage dashboardGenera el panel HTML y lo abre en tu navegador predeterminado
Create Vault Token Usage Projects reportEscribe un desglose en Markdown por vault y por proyecto, práctico para facturar a varios clientes o espacios de trabajo
Show what's newVuelve a abrir en cualquier momento la ventana de novedades de la versión instalada
Export all CSV filesEscribe las tres exportaciones CSV en tu vault, ver Exportar tus datos
Export projects CSVEl resumen por vault y proyecto en un solo CSV
Export daily detail CSVLa matriz día por vault en un solo CSV
Export key figures CSVLos indicadores clave, las lecturas oficiales de los límites y el rango de tus límites alcanzados en un solo CSV

Fuentes de datos y transparencia#

Este plugin necesita acceso directo al sistema de archivos para funcionar. La revisión de plugins de la comunidad de Obsidian lo marca como un aviso esperado, no como un defecto, porque leer archivos de sesión locales es justo su propósito. En lugar de pedirte confianza ciega, aquí tienes exactamente dónde están esos archivos, qué campos lee el plugin y qué no toca nunca. Cada afirmación se puede comprobar en el propio código: main.js no está minificado y es público en GitHub.

Dónde están realmente los archivos JSONL. Claude Code, ya se ejecute en un terminal, en un editor como VS Code o dentro de Obsidian, escribe un archivo JSONL por sesión en ~/.claude/projects/<workspace-id>/<session-id>.jsonl, una subcarpeta por directorio de trabajo. Es igual en Windows (C:\Users\<tú>\.claude\projects\...), macOS (/Users/<tú>/.claude/projects/...) y Linux (/home/<tú>/.claude/projects/...); el plugin la localiza con os.homedir() de Node, que funciona igual en todas partes. Interviene otro archivo, solo de lectura salvo que uses el ajuste de retención del plugin: el ~/.claude/settings.json de Claude Code, del que solo se lee el valor cleanupPeriodDays. Si lo cambias desde los ajustes del plugin, antes se escribe automáticamente una copia .bak del archivo completo. Y solo si configuras el feed opcional: ~/.claude/ratelimit-log.jsonl, solo lectura, los porcentajes oficiales con sus horas de reinicio.

Modo agente de Claude Desktop: una excepción solo de Windows, según lo que se sabe hoy. La versión de Windows de la app de escritorio de Claude ejecuta su Claude Code integrado dentro de un entorno aislado de contenedor de aplicaciones MSIX, que virtualiza el sistema de archivos. Por eso las sesiones del modo agente acaban allí en otro lugar: %APPDATA%\Claude\local-agent-mode-sessions\... o, en la versión de Microsoft Store, en la ruta aislada %LOCALAPPDATA%\Packages\<package-id>\LocalCache\Roaming\Claude\local-agent-mode-sessions\.... El plugin recorre automáticamente esta segunda ubicación desde la v1.8.0, solo en Windows. macOS y Linux no tienen una capa de aislamiento equivalente y, según la documentación disponible, Claude Code escribe allí en la misma ~/.claude/projects/, sea la línea de comandos, las integraciones con editores o la app de escritorio. En macOS y Linux, las sesiones del modo agente (donde existe) deberían llegar ya a la ubicación estándar que lee el plugin. Es la mejor evidencia actual, no una fuente primaria de Anthropic: si usas el modo agente en macOS o Linux y falta consumo, abre un issue en GitHub.

Campo leído de una línea de sesiónPara qué se usa
message.usageLos tokens de entrada, salida, escritura y lectura de caché: cada cifra de la barra lateral y del panel
message.modelA qué modelo pertenece la línea (Haiku, Sonnet, Opus, Fable)
cwd, sessionIdA qué vault, subproyecto y sesión pertenece un dato
timestampCuándo: base de todas las vistas temporales, de la ventana de 5 horas y del archivo
compactMetadata (entradas del sistema)Los tokens antes y después de una compactación, mostrados como evento de compactación
error (entradas del sistema)Solo para detectar límites de uso y fallos de conexión, nunca el contenido de los mensajes
aiTitleLa única excepción, ver más abajo

Lo único que no es un número. El propio Claude Code escribe un título breve, generado automáticamente, para cada sesión en el mismo archivo JSONL (una entrada ai-title). La tabla Top Sessions del panel lee esa única cadena corta y la muestra en lugar de un identificador de sesión en bruto, solo para que la lista se pueda leer. Es el único campo que procede del contenido de la conversación y no de cifras de uso, y es el resumen del propio Claude Code, nada que el plugin genere o amplíe.

Lo que nunca lee. El texto de tus prompts, las respuestas de Claude, las llamadas a herramientas, el contenido de los archivos o cualquier otra cosa de una línea de sesión más allá de los campos anteriores nunca se analizan, muestran, guardan ni envían a ningún sitio: el código sencillamente nunca abre esas claves. Compruébalo tú: busca en main.js .usage, .model, .cwd, .sessionId y .aiTitle, y encontrarás cada lugar donde este plugin toca tus datos.

Lo que sale de tu equipo: nada. Sin peticiones de red, sin telemetría, sin servidor externo: cada cifra se calcula en local. El plugin escribe exactamente dos tipos de archivos nuevos, ambos dentro de tu propio vault y ambos solo con totales: el archivo diario en Token Usage Archive/ (ver Archivo y datos a largo plazo) y, solo cuando tú lo pides, el informe en Markdown, el panel HTML, la exportación por vault y proyecto y las exportaciones CSV. Ninguno contiene nunca un prompt ni una respuesta.

Si quieres revisar el navegador tú mismo. Las herramientas de desarrollo de tu navegador (F12 → pestaña Red, filtrada por XHR/Fetch) muestran cada petición mientras usas claude.ai. Dos advertencias honestas: este plugin no hace nada de eso por ti, no tiene integración con el navegador, ni extensión, ni proxy, y es un límite deliberado. Y el cliente web de claude.ai habla con puntos de acceso internos y no documentados de Anthropic, no con la API pública de Claude que usa Claude Code: las cifras parecidas a tokens que veas allí son detalles internos que pueden cambiar sin aviso. El objeto usage de la API pública, el que Claude Code escribe en tus archivos JSONL locales y el que lee este plugin, sigue siendo la única fuente estable y documentada de recuentos exactos de tokens.

Límites: porcentajes solo de Anthropic#

Los porcentajes ahora vienen solo de Anthropic. Hasta la 2.1, Token Usage estimaba un porcentaje para la ventana de 5 horas y para la semana, a partir de tus propios límites alcanzados o extrapolado desde el feed. Comparamos esa estimación con los valores oficiales durante once días. En la ventana de 5 horas se desviaba de media 36 puntos, y en el momento en que una ventana estaba oficialmente llena, nuestro anillo marcaba cualquier valor entre el 61 y el 217 por ciento (medición propia, 37 lecturas, del 6 al 17 de octubre de 2026). Lo rápido que se llena una ventana depende mucho de cuánto contexto arrastra una sesión, y los registros locales no pueden saberlo de forma fiable. Los anillos sugerían una precisión que nunca tuvieron. Fue decisión nuestra, y fue un error.

Desde la 2.5 rige una regla sencilla: solo mostramos un porcentaje para un límite si viene de Anthropic, junto con la hora en que se leyó. Para ello necesitas el feed (ver Porcentajes oficiales de Anthropic). Hacemos una excepción con la semana: entre dos lecturas proyectamos el último valor oficial con tus tokens contados y lo indicamos como tal, porque el límite semanal resultó estable en la misma medición (1,2 puntos de desviación media). Sin el feed ves lo que sabemos con certeza: tus tokens en la ventana actual y en la semana, el tiempo hasta el reinicio y el rango en el que tu ventana de 5 horas se ha llenado hasta ahora. El anillo Hoy ya no muestra un porcentaje, sino un múltiplo de tu día habitual. Todo lo demás del plugin se cuenta y sigue igual.

AnilloCon el feedSin el feed
Ventana 5 hEl porcentaje oficial de una lectura tomada en la ventana actual, «lectura hh:mm», más los tokens contados desde entonces. Dentro de una ventana el valor oficial solo puede subir, así que es un mínimo. No se muestra una lectura de una ventana anteriorGris: tokens de la ventana actual y tiempo hasta el reinicio
Esta semanaEl porcentaje oficial. Entre lecturas se proyecta con tus tokens contados y se marca «proyectado», con el valor oficial y su hora debajo. Tras un reinicio semanal sin nueva lectura, continúa desde el 0 % con el límite de la semana anterior, marcado «proyectado desde el reinicio»Gris: tokens de esta semana y tiempo hasta el reinicio
HoyUn múltiplo de tu día habitual, por ejemplo «1,7x tu día habitual». Nunca un límite, ver El anillo HoyIgual

Por qué los tokens bajo un anillo no coinciden con su porcentaje. El plugin cuenta entrada y salida. Anthropic también cuenta el contexto que una sesión envía con cada solicitud, así que porcentaje y tokens no coinciden directamente. Una sesión larga que arrastra un contexto grande puede llenar una ventana con relativamente pocos tokens contados. Lo que vale es el porcentaje.

Lo que se queda: el rango de tus límites alcanzados. Bajo los anillos, el plugin indica la cifra de tokens más baja y la más alta con la que tu ventana de 5 horas se ha llenado hasta ahora, por ejemplo «Hasta ahora tu ventana de 5 h se llenó tras entre 51 K y 316 K (102 límites alcanzados)». Cuenta entrada y salida desde el inicio de la ventana hasta cada límite. No es un límite ni una previsión: muestra lo amplio que es realmente el rango. Con el feed, el inicio de la ventana viene de Anthropic. Sin él, se reconstruye a partir de tus registros y puede desviarse unos minutos si claude.ai u otro dispositivo abrió la ventana. Sin el feed, una línea corta bajo los anillos enlaza directamente con la configuración.

¿Por qué no una estimación mejor? Probamos una: ponderando también los tokens de caché, la semana quedaba muy cerca del valor oficial, pero la ventana de 5 horas seguía desviándose alrededor de un 25 por ciento hacia arriba o hacia abajo con nuestros propios datos. Anthropic puede cambiar en cualquier momento cómo se cuenta un límite, y una cifra en la que no puedes confiar es peor que ninguna. Los tokens contados, el reinicio y el rango son seguros; el porcentaje viene de la fuente.

Hasta la 2.1, esta sección se llamaba «Estimación empírica de límites» y decía que la estimación sería más precisa con cada límite alcanzado. La medición anterior demostró que no era así.

¿Qué es un token?#

Un token es un pequeño fragmento de texto, aproximadamente tres cuartas partes de una palabra en inglés; en español las palabras suelen dividirse en algo más de tokens. No es exactamente una palabra ni exactamente un carácter. La frase «Buenos días, ¿cómo estás hoy?» da unos 9 tokens. Las palabras largas o poco comunes cuestan más; las palabras cortas y frecuentes a veces comparten uno. Tu entrada y la respuesta de Claude se cuentan por separado.

Cada llamada a la API se factura con dos cifras: cuántos tokens entran y cuántos tokens salen. Es todo lo que cuenta para la factura.

Entrada y salida#

La entrada (input) es todo lo que Claude recibe en una petición: tu mensaje, el prompt del sistema, el contenido de los archivos, los resultados de las herramientas y el historial de la conversación, que se reenvía en cada turno.

La salida (output) es lo que Claude escribe de vuelta. Los tokens de salida son siempre más caros que los de entrada en todos los modelos, normalmente entre 3 y 5 veces.

Una pregunta suelta es barata. Los costes crecen con el volumen, el tamaño del contexto y la repetición, no con la complejidad de lo que preguntas.

C.Escritura — escritura en caché#

Cuando Claude Code envía un bloque de texto grande y repetido (archivos del proyecto, un prompt del sistema largo, una base de código entera), la infraestructura de Anthropic puede guardarlo en caché. La primera vez que se procesa ese bloque, se escribe en la caché. Eso es una escritura en caché.

Hay dos tipos de escritura en caché, con precios distintos: una escritura en caché de 5 minutos cuesta 1,25 veces el precio de entrada estándar, una escritura en caché de 1 hora cuesta 2 veces. En nuestros propios registros, cerca del 90 % de las escrituras en caché de Claude Code con suscripción eran 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 para ese periodo. Es una inversión: pagas más al principio para que las peticiones siguientes no tengan que volver a procesar el mismo contenido. Las escrituras en caché también cuentan para el límite de 5 horas, ver Qué cuenta para un límite.

El plugin muestra C.Escritura en aguamarina en toda la barra lateral.

C.Lectura — lectura de caché#

Una vez que un bloque está en caché, Claude puede leerlo desde la caché en las peticiones siguientes en lugar de procesarlo desde cero. Eso es una lectura de caché.

Las lecturas de caché cuestan solo una fracción del precio de entrada estándar: 0,1 veces en la mayoría de los modelos, 0,05 veces en Opus 5.5 y Sonnet 5.5, 0,025 veces en Fable 5.1. Si el mismo contexto se usa muchas veces, las lecturas de caché hacen que las sesiones grandes resulten bastante más asequibles de lo que serían.

El plugin muestra C.Lectura en violeta para indicar mucho volumen con poco coste por token.

C.Escritura vs C.Lectura — el factor de reutilización y lo que dice de tu forma de trabajar#

La relación entre estas dos cifras es más que un detalle de costes: es una lectura directa y honesta de si un tramo de trabajo fue concentrado o disperso.

Factor de reutilización = C.Lectura ÷ C.Escritura

FactorQué indica
≥ 8×Concentración profunda: excelente rendimiento de la caché, el mismo contexto sostiene muchas peticiones.
3–8×Equilibrado: trabajo enfocado con algo de variedad.
1–3×Exploratorio: contexto nuevo con frecuencia, típico de la investigación o de acotar una tarea.
< 1×Reutilización mínima: sobre todo sesiones cortas e independientes.

Una reutilización alta significa que seguiste en el mismo contexto con preguntas de seguimiento en lugar de empezar una y otra vez; una baja significa cambios de contexto casi constantes. Ninguna de las dos es «incorrecta», explorar tiene su sitio, pero si querías un trabajo profundo y sostenido y el factor dice otra cosa, conviene fijarse. El panel muestra esta proporción en la sección de eficiencia de la caché, con un gráfico de líneas con C.Escritura en aguamarina y C.Lectura en violeta, igual que en la barra lateral.

Focus Score, una segunda señal independiente. El Focus Score del panel (0 a 100) combina tres cosas que el plugin ya ve: reutilización de la caché (los tramos de arriba, el 50 % de la puntuación), continuidad (pocas sesiones largas por día activo puntúan más que muchas cortas, 30 %) y profundidad (más idas y vueltas por sesión puntúan más que preguntas sueltas, 20 %). El resultado da una insignia: Deep Work Mode (80 o más), Focused (60 o más), Balanced (40 o más) o Scattered (menos de 40).

Leer las dos señales juntas, en la práctica. Un factor de reutilización y un Focus Score altos en un día en que estuviste metido a fondo en un problema son una buena señal, no una cifra de vanidad: Claude reutilizó lo que ya entendía de tu contexto en lugar de volver a deducirlo, lo que es más barato y suele ser más rápido. Si salen bajos un día en que pensabas estar concentrado, las causas probables son: reescribir o volver a pegar un contexto largo en lugar de seguir el mismo hilo, abrir una sesión nueva para preguntas que pertenecían a la anterior, o alternar rápido varias tareas sin relación. Todo eso se ve directamente en estas cifras, días o semanas después.

Para empezar: el hábito más eficaz es quedarse en una sesión continua para un problema continuo y hacer preguntas de seguimiento en lugar de volver a explicar el contexto en un mensaje nuevo. Eso suele subir ambas cifras y, de paso, es una mejor forma de trabajar. Para usuarios avanzados: un factor bajo de forma constante en todo un proyecto puede indicar que el prompt del sistema o el contexto compartido se reconstruye cada vez en lugar de reutilizarse. Merece la pena corregirlo en el flujo de trabajo (sesiones más largas, un archivo de referencia compartido, subagentes que heredan el contexto) en vez de aceptarlo como un coste normal.

Ventana actual de 5 horas#

Claude Code aplica una ventana de 5 horas, y es anclada, no móvil. La ventana se abre con tu primer mensaje y dura exactamente cinco horas; una nueva solo empieza cuando ese tramo ha transcurrido por completo, encadenada en bloques fijos de cinco horas, sin importar cuánto tiempo de inactividad haya 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 y no inicia una nueva ventana de 5 horas.

El plugin reconstruye esas ventanas reales a partir de tu actividad y suma la que está abierta, con entrada, salida, C.Escritura y C.Lectura en filas separadas. Esto importa justo cuando una ventana cambia: un cálculo móvil sumaría el final de la ventana que acaba de cerrarse al principio de la que acaba de abrirse y daría una cifra que no pertenece a ninguna, precisamente cuando más quieres ver que tienes presupuesto nuevo.

Es la vista más inmediata de tu trabajo actual. Si llevas un rato trabajando sin una pausa larga, esta ventana recoge lo que has gastado desde que se abrió.

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

La cuenta atrás del reinicio, al pie de la barra lateral, dice «Claude 5h resets in: ~Xh Ym». La tilde es intencionada: indica 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 momento en que envías tu primer mensaje. Al empezar una sesión, la primera petición suele ser larga: cargar contexto, leer archivos, pensar. Esa primera respuesta puede tardar de 10 a 25 minutos, y durante ese tiempo todavía no se escribe nada en el registro local. Así que la marca de tiempo más temprana que el plugin puede leer no es el inicio real de tu sesión, sino el momento en que llegó tu primera respuesta.

Por eso la cuenta atrás del plugin puede ir de 10 a 25 minutos por detrás de la de 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 lo que muestra Claude es la fuente de referencia.

Con el feed (ver Porcentajes oficiales de Anthropic) esa diferencia desaparece: cada lectura incluye el momento en que se reinicia la ventana actual. En cuanto hay una lectura de la ventana actual, el plugin usa el inicio oficial, aunque la ventana se abriera en claude.ai, en otro dispositivo o en otra herramienta.

Las tres vistas temporales y cómo se relacionan#

La barra lateral muestra tres resúmenes distintos de tu actividad: Ventana actual de 5 horas, Esta sesión y Hoy. Son tres cortes independientes de los mismos datos: no se anidan automáticamente unos dentro de otros como lo harían horas, días y semanas.

VistaQué abarcaSe reinicia cuando
Ventana actual de 5 horasVentana anclada: todo desde que se abrióCaduca: el siguiente mensaje abre una nueva, en pasos fijos de cinco horas sin importar las pausas
Esta sesiónTodas las entradas con el identificador de sesión actual, sea cual sea la fechaEmpiezas una nueva sesión de Claude Code (nuevo archivo JSONL)
HoyDía natural: todo desde medianocheCada día a medianoche

La consecuencia clave: una sesión puede abarcar varios días. Si ayer empezaste una sesión larga y hoy la continuaste, «Esta sesión» mostrará más tokens que «Hoy». Es lo esperado: la sesión acumula a través de los cambios de día, mientras que «Hoy» solo cuenta desde esta medianoche.

Del mismo modo, la ventana de 5 horas no es una parte de «Hoy»: una ventana que se abrió ayer a última hora cruza la medianoche, y todo lo que contiene sigue contando para el mismo límite. También pueden coincidir: si tu ventana se abrió esta mañana y hoy no habías trabajado antes, ambas cifras son iguales hasta que la ventana se cierra.

El plugin lo hace visible: una pequeña línea bajo el título de cada sección indica su alcance. «Esta sesión» muestra cuándo empezó la sesión, para que veas al instante si las cifras abarcan varios días.

Modelos#

Claude Code envía las peticiones a distintos modelos según la tarea. La barra lateral muestra una barra de porcentajes apilada con la distribución de modelos de los últimos 7 días, cada familia en su propio color:

ModeloColor en la barra lateralPapel típico
HaikuVerde azuladoTareas rápidas y ligeras, el coste más bajo
SonnetAzulEquilibrio entre capacidad y coste
OpusRosaRazonamiento complejo, trabajo exigente
FableVioletaLa mayor capacidad, el mayor coste
OtrosGrisNombres de modelo desconocidos o futuros

Los colores de los modelos evitan a propósito el verde, el ámbar y el rojo. En este plugin esos tres significan bien, aviso y crítico: un color identifica algo o lo valora, nunca las dos cosas. Hasta octubre de 2026, las páginas de ayuda en otros idiomas aún mostraban los colores anteriores a la 2.0 (cian, azul, morado, ámbar).

Conocer tu mezcla de modelos explica buena parte de la variación de costes de un día a otro. Un día con mucho Opus cuesta algo muy distinto a un día pasado casi todo en Haiku. Para la gama actual de modelos y los precios exactos, la página de precios de Anthropic es la referencia, ver también Precios de la API más abajo.

Sesiones#

Claude Code escribe un archivo de registro JSONL por sesión. El plugin lee todos los archivos de ~/.claude/projects/ y agrupa el consumo por sesión. La tabla Top Sessions del panel muestra qué ejecuciones consumieron más tokens, útil para detectar sesiones inesperadamente caras.

Qué cuenta para un límite#

Anthropic aplica dos límites y nada más: la ventana de 5 horas de arriba y un tope semanal que se reinicia en un momento fijo. No hay límite diario, así que el anillo Hoy no es una cuota (ver El anillo Hoy).

Cuentan los tokens de entrada y de salida, y la caché tampoco es gratis. Las mediciones frente a los porcentajes oficiales que informa Claude Code (octubre de 2026) indican que las escrituras en caché cuentan claramente para la ventana de 5 horas y las lecturas de caché un poco. Un análisis anterior de los límites alcanzados apuntaba en sentido contrario; las mediciones nuevas 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, el valor 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 rápido por respuesta que las sesiones cortas y nuevas.

Anthropic no publica ninguno de los dos límites en tokens. Por eso, desde la 2.5, Token Usage solo muestra un porcentaje para un límite si viene de Anthropic, siempre con la hora de la lectura (ver Límites: porcentajes solo de Anthropic). Para ello hace falta el feed, un pequeño archivo con los porcentajes oficiales (ver Porcentajes oficiales de Anthropic). Entre dos lecturas, la semana se proyecta con tus tokens contados y se marca «proyectado». La ventana de 5 horas no, porque lo rápido que se llena depende sobre todo de cuánto contexto arrastra una sesión, y los registros locales no pueden saberlo de forma fiable. Sin el feed ves los tokens contados, el tiempo hasta el reinicio y el rango en el que tu ventana de 5 horas se ha llenado hasta ahora.

El anillo Hoy#

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

Desde la 2.5 lo muestra como un múltiplo, no como un porcentaje: «2,0x tu día habitual» significa que hoy trabajas el doble de lo normal, nada más. Un día intenso es un cambio en tu forma de trabajar, no un aviso, por eso el anillo se queda en gris neutro (desde la 2.1.0). Lo cerca que estás de un límite lo muestran solo los anillos de la ventana de 5 horas y de la semana, y solo con un valor oficial. Hasta la 2.1 la misma comparación decía «200 %»; con el múltiplo, cada porcentaje en pantalla viene de Anthropic o es una proyección semanal marcada a partir de un valor de Anthropic.

Porcentajes oficiales de Anthropic (el feed)#

Opcional, desde la 2.1.0. 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. Desde la 2.5, este archivo es la única fuente de porcentajes de límite en Token Usage: sin él, los anillos de la ventana de 5 horas y de la semana se quedan en gris y muestran los tokens contados y el tiempo hasta el reinicio; todo lo demás funciona igual. La guía completa (en inglés) está en la carpeta extras de GitHub.

Qué ganas

Sin feedCon feed
Inicio de la ventana de 5 horasReconstruido a partir de tu primer mensaje registradoEl inicio oficial, también cuando la ventana se abrió en claude.ai, en otro dispositivo o en otra herramienta
Anillo de 5 horasGris: tokens de la ventana y tiempo hasta el reinicioEl porcentaje oficial de una lectura de la ventana actual, con su hora y los tokens contados desde entonces
Anillo semanalGris: tokens de la semana y tiempo hasta el reinicioEl porcentaje oficial, proyectado entre lecturas con tus tokens contados y marcado «proyectado»
Reinicio semanalDel mensaje de límite semanal, una vez que has llegado al topeDel feed, al minuto, también con el cambio de hora

Un ejemplo real de nuestros propios datos, 27 de octubre de 2026: a las 13:10 el plugin proyectaba la semana desde un 24 % oficial hasta cerca del 28 %; la siguiente lectura oficial, seis minutos después, dio un 29 %.

Requisitos

  • Una suscripción Pro o Max con la que Claude Code haya iniciado sesión. Con una clave de 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. Claude Code instalado con el instalador nativo no trae Node.js.
  • Una versión reciente de Claude Code y, para la consulta programada, la línea de comandos claude.

¿Qué script necesito?

Dónde trabajasScript
En un terminalratelimit-statusline.js como línea de estado. Gratis, las lecturas llegan mientras trabajas
Dentro de Obsidian, un editor u otro cliente sin línea de estadoratelimit-poll.js, ejecutado de forma programada
AmbosLos dos. Escriben en el mismo archivo

Una línea de estado solo funciona mientras el terminal interactivo de Claude Code está abierto. Los clientes que integran Claude Code no la ejecutan, así que allí la línea de estado 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 haya:

"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 y diminuta (el prompt ok a Haiku, sin guardar sesión) y cuenta para 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 trabajes de todos modos; tres veces al día bastan de sobra para la semana, que el plugin proyecta entre lecturas. El anillo de 5 horas solo muestra una lectura de la ventana actual, así que con tres consultas al día estará en gris la mayor parte del tiempo; es el estado honesto, no un error. Desde la 2.5 el script lo intenta una vez más tras un tiempo de espera agotado: una ejecución justo al salir de la suspensión a menudo aún no tiene red.

O solo mientras trabajas (desde la 2.5, recomendado si quieres ver el anillo de 5 horas). Iniciado con --only-when-active, el script comprueba primero si Claude Code ha escrito en sus registros de sesión en los últimos 20 minutos y, si no, termina sin hacer ninguna petición. Mientras trabajas ya hay una ventana de 5 horas abierta, así que la consulta prácticamente nunca abre una por su cuenta y puede ejecutarse cada hora. El anillo de 5 horas muestra entonces un valor oficial la mayor parte del tiempo que trabajas. Cada ejecución con actividad es una petición diminuta; las ejecuciones sin actividad no cuestan nada. Hasta la 2.5.0 recomendábamos cada 30 minutos: el doble de peticiones para una lectura como mucho media hora más reciente. Los comandos de esta variante para Windows, macOS y Linux están en la guía de la carpeta extras enlazada arriba; con cron es simplemente 0 7-23 * * * con la opción al final.

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, recupera las ejecuciones perdidas si el equipo estaba apagado y no abre ninguna ventana de consola):

$node     = (Get-Command node).Source
$script   = "$env:USERPROFILE\.claude\ratelimit-poll.js"
$action   = New-ScheduledTaskAction -Execute 'conhost.exe' -Argument "--headless `"$node`" `"$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

Por qué conhost.exe --headless (desde la 2.5.1): node.exe es un programa de consola, así que el Programador de tareas abre una ventana de consola en cada ejecución, incluso en las que no consultan nada. Hasta la 2.5.0 nuestros comandos iniciaban node.exe directamente y hacían justo eso. Iniciada así, la ejecución queda invisible. Lo hemos probado en Windows 11. Microsoft no documenta esta opción, y algunos programas de seguridad marcan como sospechosos los inicios de consola ocultos. Si el tuyo lo hace, o la tarea no se ejecuta, usa en su lugar -Execute $node -Argument "`"$script`"" y acepta la ventana breve.

¿Ya la programaste con una guía anterior? Esto conserva tu tarea, tus horas y tus opciones y solo añade el inicio invisible:

$old = (Get-ScheduledTask -TaskName 'TokenUsageLimitPoll').Actions[0]
if ($old.Execute -notmatch 'conhost') {
  $new = New-ScheduledTaskAction -Execute 'conhost.exe' -Argument "--headless `"$($old.Execute)`" $($old.Arguments)"
  Set-ScheduledTask -TaskName 'TokenUsageLimitPoll' -Action $new
}

macOS y Linux (crontab -e, con rutas completas obtenidas con 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, define CLAUDE_BIN con su ruta completa.

Comprobar que funciona

  • El archivo ~/.claude/ratelimit-log.jsonl existe y recibe líneas nuevas.
  • Actualiza la barra lateral. El anillo semanal muestra un porcentaje con «lectura hh:mm» (o «proyectado» con el valor oficial debajo), y el aviso «Los porcentajes oficiales necesitan el feed.» bajo los anillos ha desaparecido. El anillo de 5 horas muestra un porcentaje justo después de una lectura en la ventana actual. En el panel, los recuadros indican «official percentage from Anthropic» o «projected from the last official value».
  • 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

  • Inicio de la ventana: cada lectura incluye el momento en que se reinicia la ventana de 5 horas actual. La ventana son las cinco horas anteriores, así que el plugin conoce el inicio real aunque la ventana se abriera donde él no puede ver.
  • Anillo de 5 horas: muestra la última lectura solo mientras su ventana sigue abierta, con la hora de la lectura y los tokens contados desde entonces. Dentro de una ventana el valor oficial solo puede subir, así que es un mínimo. No se proyecta nada. No se muestra una lectura de una ventana anterior.
  • Anillo semanal: muestra la última lectura de la semana actual. Entre lecturas se proyecta con tus tokens contados frente al límite semanal que se deduce de las lecturas (tokens de la semana hasta una lectura divididos por su porcentaje, a partir de lecturas del 10 % o más; por debajo, el redondeo a enteros es demasiado grueso) y se marca «proyectado». Tras un reinicio semanal sin nueva lectura, continúa desde el 0 % con el límite de la semana anterior, marcado «proyectado desde el reinicio».
  • Créditos de uso: con créditos de uso (usage credits) puedes seguir trabajando después del límite semanal. Las lecturas del 100 % o más, y todo lo posterior en la misma semana, no se usan para el límite semanal; una semana al 100 % muestra el valor oficial sin proyectarlo.
  • Reinicio semanal: se toma de la lectura como un momento exacto, así que sigue siendo correcto con el cambio de hora.
  • Otras ventanas: si Anthropic informa de algo más que la ventana de 5 horas y la semana (por ejemplo, un límite semanal propio para un modelo), los dos scripts lo registran y el plugin lo muestra bajo los anillos, tal como llega.
  • Un tiempo sin feed: sin una lectura adecuada, los anillos vuelven a gris y muestran los tokens contados y el tiempo hasta el reinicio. Entre medias no se estima nada.

Límites conocidos

  • La proyección semanal solo cuenta entrada y salida. Oficialmente también cuentan las escrituras en caché (las lecturas un poco). A lo largo de una semana se compensa bien (1,2 puntos de desviación media en nuestra medición), pero una gran reconstrucción de la caché solo se ve por completo con la siguiente lectura.
  • Solo hay lecturas cuando un script se ejecuta: mientras se muestra una línea de estado o en las horas programadas.
  • Porcentajes enteros: los valores oficiales llegan redondeados. Un uno por ciento de una ventana de 5 horas pueden ser unos miles de tokens.

Solución de problemas

Lo que vesQué hacer
La línea de estado está vacíaNo se encuentra Node.js. Comprueba node --version; en Windows pon la ruta completa de node.exe en el comando
5h ? | week ?No llegan porcentajes. Inicia sesión con tu suscripción en lugar de una clave de API y actualiza Claude Code
Consulta: «Claude Code CLI not found»Define CLAUDE_BIN con la ruta completa de claude
Consulta: «No rate_limit_event in the output»Ejecuta claude una vez a mano e inicia sesión con tu suscripción
Anillo de 5 horas en gris con «aún no hay lectura en esta ventana»Normal entre consultas a horas fijas. Ejecuta la consulta una vez a mano y actualiza, o prográmala cada hora con --only-when-active
Windows: se abre una ventana de consola en cada consultaLa tarea inicia node.exe directamente (nuestra guía hasta la 2.5.0). Cambia al inicio invisible, ver «¿Ya la programaste con una guía anterior?»
Windows: la tarea con --headless no se ejecuta, o un programa de seguridad la marcaUsa el inicio simple con node.exe y acepta la ventana breve
Anillo semanal en gris con «aún no hay lectura esta semana»No hay lectura desde el reinicio semanal y tampoco la hubo la semana anterior. Espera a la siguiente lectura o ejecuta la consulta una vez a mano

Privacidad y eliminación

Todo se queda en tu equipo. Cada línea contiene una marca de tiempo, los porcentajes con sus horas de reinicio y, desde la línea de estado, el identificador de sesión y de 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. Los anillos de la ventana de 5 horas y de la semana se quedan entonces en gris y muestran los tokens contados y el tiempo hasta el reinicio.

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 funciona en clientes como Obsidian. Ambas cosas se han añadido. Actualizado para la 2.5: hasta la 2.1 el plugin usaba las lecturas para corregir sus propias estimaciones de límite y, sin ellas, volvía a esas estimaciones; desde la 2.5 las lecturas son la única fuente de porcentajes.

Reinicio semanal#

El límite semanal se reinicia en un momento fijo, distinto en cada cuenta. Todo lo semanal depende de él: el anillo semanal, la previsión y el mapa de actividad.

Normalmente no tienes que ajustar nada. Con el feed, el plugin toma el reinicio exacto de la lectura oficial. Sin él, lo lee del mensaje que escribe Claude cuando alcanzas un límite semanal. En ambos casos, los ajustes muestran una marca verde y de dónde viene el valor. Mientras no se haya detectado ningún reinicio, el plugin supone domingo a las 18:00 y lo dice.

Cambio de hora. El reinicio de Anthropic está fijado en UTC, por eso su hora local se desplaza una hora cuando cambia la hora. Hasta la 2.1 el plugin lo guardaba como día de la semana y hora local, de modo que tras el paso al horario de invierno cada límite de semana quedaba una hora desplazado. Desde la 2.5, un reinicio detectado se guarda como un momento exacto y sigue el cambio automáticamente.

Puedes fijarlo a mano en Ajustes → Reinicio semanal. Un ajuste manual prevalece y se queda en hora local: la detección automática no lo sobrescribe, solo lo confirma.

Una barra de iconos a la izquierda cambia entre cuatro páginas. Desde la 2.0 es la única disposición; la antigua vista «Classic» y el ajuste para cambiar entre ambas se han eliminado.

PáginaQué contiene
ResumenTres anillos (Ventana 5 h, Hoy, Esta semana) con el rango de tus límites alcanzados debajo, el mapa de actividad de la semana de facturación actual, tu última acción y el desglose de tokens. Los anillos de la ventana de 5 horas y de la semana solo llevan un porcentaje si viene de Anthropic, con la hora de la lectura; sin él se quedan en gris y muestran los tokens contados y el tiempo hasta el reinicio. El anillo Hoy muestra un múltiplo de tu día habitual
CalendarioLos dos últimos meses como cuadrículas mensuales
AnalíticasLos resúmenes de 7 días y de N días como fichas de indicadores con líneas de tendencia, más la distribución de modelos
AjustesLos mismos ajustes que en la pestaña de ajustes de Obsidian, sin salir de la barra lateral

Todo lo que hay en Resumen es, a propósito, de hoy o de la semana actual; lo que abarca un periodo más largo está en Analíticas o en el panel. En la cabecera, Dashboard y Report generan archivos, CSV exporta a tu vault y la flecha fuerza una actualización inmediata.

Cada una de las cuatro filas de tokens de Resumen lleva un pequeño indicador: un punto verde cuando el valor está cerca de tu propia media reciente, una flecha ámbar cuando va claramente por encima. El periodo 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 Resumen cubre tu semana de facturación actual. Una fila por día natural, una celda por cada dos horas, doce celdas al día.

Tiene ocho filas, no siete: una semana que va, por ejemplo, del domingo a las 17:00 al domingo siguiente a las 17:00 toca ocho fechas, así que la primera y la última fila son parciales a propósito. Las celdas fuera de la ventana se dibujan como contornos vacíos; eso es lo que hace visible el límite de tu ciclo en lugar de esconderlo en franjas artificiales de 24 horas.

El color compara cada celda con tu propio bloque habitual de 2 horas: la media de todos los bloques de 2 horas con actividad en los días guardados (el valor aparece bajo la cuadrícula). Bajo es menos de la mitad, medio hasta ese valor, alto hasta el doble, rojo más del doble. El matiz dentro de un tramo muestra dónde se sitúa una celda en él. Hasta la 2.1 las celdas se medían frente a un límite de 5 horas estimado, que ya no existe.

Se distinguen tres tipos de nada: fuera de la ventana (solo contorno), todavía no alcanzado (tenue) y sin actividad de verdad (relleno). Solo el último 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 alguna actividad.

Calendario de actividad

La página Calendario muestra los dos últimos meses uno junto a otro. Dos en lugar de uno, porque al principio de un mes una sola cuadrícula mostraría apenas unos pocos días útiles y ocultaría justo el periodo previo que buscas. Las flechas llevan el par más atrás, hasta donde llega el archivo; el calendario nunca va al futuro.

Cada día pasado lleva un punto de color medido frente a tu propia media diaria reciente: verde por debajo, ámbar en torno a ella, rojo en un pico (2x o más). Los días sin actividad no tienen punto. Haz clic en un día para añadir 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 formas de 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 indicada en Ajustes → Carpeta de exportación CSV en el vault. El menú nombra esa carpeta antes de que hagas clic. Las mismas exportaciones están en la paleta de comandos bajo «Export».

Menú de exportación CSV del panel: el panel es una página del navegador, así que entrega el archivo a tu navegador y es este quien decide dónde va, normalmente tu carpeta de descargas. Una página web no puede elegir una carpeta de destino; es una norma de los navegadores, no una función que falte.

Ambas vías producen números en bruto y fechas ISO, listos para calcular en Excel, Sheets o un script. Todo se genera en local: sin subidas, sin red, igual que el resto del plugin.

Los indicadores clave siguen la misma regla que los anillos (desde la 2.5): los valores oficiales de la ventana de 5 horas y de la semana con la hora de la lectura, la proyección semanal marcada, el límite semanal que se deduce del feed y el rango de tus límites alcanzados (el más bajo y el más alto). Las antiguas filas con límites estimados han desaparecido. Las celdas de texto que empiezan por =, +, - o @, como un nombre de carpeta poco habitual, llevan un apóstrofo delante para que Excel o LibreOffice no puedan ejecutarlas como fórmula; los números siguen igual.

Archivo y datos a largo plazo#

Por qué existe. Claude Code gestiona sus propios archivos de sesión locales y los borra según un calendario: 30 días por defecto, controlado por cleanupPeriodDays en su propio ~/.claude/settings.json. Sin una copia en otro sitio, todo lo anterior simplemente desaparece.

Qué se escribe, y dónde. Cada vez que Obsidian está abierto (en cada actualización, por la consulta periódica o el vigilante de archivos), el plugin comprueba qué días recientes tienen ya un archivo y escribe uno para cada día que falte, incluido hoy, que se actualiza a lo largo del día. Los archivos van a una carpeta normal de tu vault, uno por día natural: Token Usage Archive/AAAA-MM-DD.md (nombre de carpeta configurable en los ajustes). Cada archivo contiene solo totales: tokens por tipo, número de sesiones, volumen de tokens por modelo y el desglose por vault y proyecto de ese día, nunca un prompt, una respuesta ni nada parecido a contenido de conversación.

Una vez escrito, el archivo de un día pasado se considera definitivo y no se toca en actualizaciones posteriores. La única excepción deliberada: cuando una versión añade una fuente de datos totalmente nueva (las sesiones del modo agente de la app de escritorio llegaron así en la v1.8.0), una reconstrucción única reescribe una vez los días recientes afectados, para que los totales incompletos de antes de existir esa fuente no se queden mal para siempre.

El límite honesto. El archivo solo puede guardar lo que todavía existe en el momento en que Obsidian está realmente abierto. Si Obsidian permanece cerrado más tiempo que el periodo de retención de Claude Code, los días intermedios se borran antes de que el plugin pueda verlos; no hay forma de evitarlo sin funcionar de manera continua. Si abres Obsidian menos de una vez al día, aumenta Ajustes → Retención de datos de Claude (escribe directamente en el cleanupPeriodDays de Claude Code, con una copia .bak automática antes) para tener más margen. Para un control serio a largo plazo, como tendencias de costes o comparar contratos a lo largo de meses, 90 a 180 días es más realista que los 30 por defecto.

El archivo se puede desactivar por completo (Ajustes → Activar archivo diario) si prefieres que el plugin nunca cree archivos en tu vault; todo sigue funcionando, pero el alcance histórico se limita entonces a lo que Claude Code aún conserve en disco.

Panel e informes por vault y proyecto#

La barra lateral está pensada para un vistazo rápido; el panel HTML (paleta de comandos → «Open Token Usage dashboard») está pensado para sentarse con las cifras. Genera de nuevo un archivo HTML estático y lo abre en tu navegador: una instantánea, no una conexión en vivo, con su fecha y hora honestamente indicadas en la esquina.

Tres pestañas. Dashboard: los recuadros de presupuesto de la ventana de 5 horas, de hoy y de la semana, luego cinco tarjetas de indicadores (Weekly Forecast, Limit Health, Cache Efficiency, Daily Velocity, Focus Score), una barra de la semana, el gráfico diario, la distribución de modelos, el histograma, Top Sessions y los límites de uso que has alcanzado, con su rango. Reports: las mismas cifras con la estructura del informe en Markdown. Projects: el desglose por vault y proyecto, más abajo.

La misma regla que en la barra lateral (desde la 2.5): los recuadros de presupuesto, la zona general, la tarjeta Limit Health y el veredicto de la barra de la semana usan solo valores oficiales, con la hora de la lectura, o la proyección semanal marcada que se deriva de ellos. Sin el feed, los recuadros muestran los tokens contados y el tiempo hasta el reinicio, y Limit Health remite a la configuración en lugar de adivinar. El Weekly Forecast se mantiene: proyecta tu propio consumo contado hasta el final de la semana de facturación, no es un límite.

El menú de periodo (30/60/180/360 días) recalcula al instante, en el navegador, las tarjetas de resumen, el gráfico diario y el de caché; siempre va integrada una ventana completa de 360 días. La distribución de modelos, el histograma, Top Sessions y la detección de límites de uso se quedan en la ventana de datos en vivo, porque el archivo que alimenta los periodos largos solo guarda totales diarios, no ese nivel de detalle por sesión. Esto también vale para el rango de tus límites alcanzados: se mide con los tokens contados hasta cada límite, que solo conserva la ventana en vivo.

Los nombres de carpetas y de modelos se escapan (desde la 2.5). El nombre de proyecto del panel es la última carpeta del directorio de trabajo en el que empezó una sesión. Hasta la 2.1, el panel insertaba esos nombres en la página sin escaparlos, así que un nombre de carpeta manipulado, por ejemplo el de un repositorio clonado, podría haber ejecutado código en la página del panel en tu navegador. Lo encontramos en nuestra propia revisión de seguridad en octubre de 2026 y no tenemos ningún indicio de que se haya aprovechado. La barra lateral dentro de Obsidian no estaba afectada.

Pestaña Projects, para más de un vault o cliente. Cada fila es una carpeta en la que empezó una sesión de Claude Code: tu vault de Obsidian, el grupo del modo agente de la app de escritorio (mostrado como Claude Desktop (Agent Mode)) o cualquier otro directorio en el que ejecutaras Claude Code directamente. Las carpetas por debajo del 1 % del total se agrupan en una sola fila «Other». Marca «Show sub-project detail» para desplegar, dentro de la propia tabla, cualquier vault cuyo directorio de trabajo cambió durante una sesión; el mismo desglose está también en la exportación independiente Vault_Token_Usage_Projects.md, práctica para repartir costes entre clientes al facturar. Las columnas se ordenan haciendo clic en su cabecera.

Comandos de exportación (paleta de comandos), cada uno sobrescribe su archivo de destino en tu vault en cada ejecución: Create Token Usage report (Token Usage Report.md), Open Token Usage dashboard (Token Usage Dashboard.html), Create Vault Token Usage Projects report (Vault_Token_Usage_Projects.md). Las tres rutas se pueden configurar, ver Referencia de ajustes.

Qué se mide (y qué no)#

El plugin cubre todas las formas en que usas Claude Code: terminal, Obsidian, un editor como VS Code y el modo agente de la app de escritorio, todo va a las mismas cifras (ver Fuentes de datos y transparencia para el detalle). Lo que no puede mostrar es el chat normal: las conversaciones en la ventana de chat habitual de la app de escritorio de Claude o en claude.ai en un navegador. Esas nunca escriben recuentos de tokens en disco en el formato que lee este plugin; la única señal disponible allí es un porcentaje redondeado del límite de tu plan. Si un día te parece más intenso de lo que muestra el panel, muy a menudo es por esto.

Referencia de ajustes#

Cada ajuste del plugin, en el orden en que aparece en Ajustes → Token Usage. Los valores por defecto están elegidos para que una instalación nueva funcione bien sin tocar nada.

AjustePor defectoQué hace
IdiomaInglésIdioma de la interfaz del plugin (inglés, alemán, francés, italiano, español). Se aplica al instante.
Reinicio semanaldetectado automáticamenteCuándo se reinicia tu límite semanal. Se toma del feed o de tus propios mensajes de límite semanal como un momento exacto, así que sigue el cambio de hora; un ajuste manual siempre prevalece y se queda en hora local. Ver Reinicio semanal.
Periodo del informe30 díasHasta dónde miran atrás el panel y el informe. Más allá de tu retención de datos de Claude, los días anteriores se completan automáticamente desde el archivo.
Activar archivo diarioActivadoEscribe un pequeño resumen en Markdown por día en tu vault. Desactívalo si no quieres que el plugin cree archivos en tu vault.
Retención de datos de Claude30 días (valor por defecto de Claude Code)Cuánto tiempo conserva Claude Code sus propios archivos de sesión, leído de los ajustes de Claude Code y, si lo cambias aquí, escrito de vuelta en ellos.
Intervalo de actualización automática30 segundosConsulta de respaldo; el vigilante de archivos ya detecta por sí solo las nuevas respuestas de Claude, a más tardar en 30 segundos.
Ruta del informe en el vaultToken Usage Report.mdRuta relativa al vault del informe en Markdown.
Ruta del informe de proyectos en el vaultVault_Token_Usage_Projects.mdRuta relativa al vault de la exportación independiente por vault y proyecto.
Ruta del panel en el vaultToken Usage Dashboard.htmlRuta relativa al vault del panel HTML.
Carpeta de archivo en el vaultToken Usage ArchiveCarpeta relativa al vault con los archivos diarios.
Carpeta de exportación CSV en el vaultToken Usage ExportsCarpeta relativa al vault en la que el plugin escribe las exportaciones CSV. Ver Exportar tus datos.

Cada campo de ruta o carpeta tiene al lado un botón «Mostrar en la carpeta» que abre la ubicación exacta en el explorador de archivos de tu sistema.

Precios de la API#

Precios de la API de Anthropic por millón de tokens, entrada y salida estándar, a octubre de 2026:

ModeloEntrada / 1MSalida / 1M
Haiku 5.5 *0,10 $0,50 $
Haiku 4.51,00 $5,00 $
Sonnet 5.52,00 $10,00 $
Sonnet 5 **2,00 $10,00 $
Sonnet 4.63,00 $15,00 $
Opus 5.54,00 $20,00 $
Opus 55,00 $25,00 $
Fable 5.110,00 $50,00 $
Fable 510,00 $50,00 $

* Haiku 5.5 para prompts de hasta 100.000 tokens; por encima, 0,50 $ de entrada / 2,50 $ de salida.
** Sonnet 5 salió con 2 $ / 10 $ como precio de lanzamiento hasta el 31 de agosto de 2026. Anthropic lo ha convertido después en el precio estándar; la subida anunciada a 3 $ / 15 $ no se produjo. La versión anterior de esta página todavía decía otra cosa.

Precios de caché sobre el precio de entrada estándar:

  • C.Escritura: 1,25 veces el precio de entrada estándar del modelo para una caché de 5 minutos, 2 veces para una caché de 1 hora (la habitual en Claude Code con suscripción)
  • C.Lectura: 0,1 veces el precio de entrada estándar del modelo; 0,05 veces en Opus 5.5 y Sonnet 5.5, 0,025 veces en Fable 5.1

Son precios de uso de la API, no precios de suscripción mensual de la app de Claude ni de Claude Code Max. El plugin Token Usage lee datos registrados en local: no hace llamadas a la API ni tiene acceso a tu cuenta de facturación de Anthropic.

Por qué se acumulan los costes#

Una petición suelta rara vez es cara. Cálculo rápido con Sonnet 5 a su precio estándar de 2 $ / 10 $ por millón:

  • 10.000 tokens de entrada × 2 $ / 1M = 0,02 $
  • 2.000 tokens de salida × 10 $ / 1M = 0,02 $
  • Total: unos 0,04 $

Eso es casi nada. El problema es la repetición y el crecimiento del contexto. Cada mensaje nuevo de una sesión suele reenviar como entrada el historial de la conversación y los archivos abiertos. Tras diez intercambios, el décimo mensaje lleva los nueve turnos anteriores más los documentos adjuntos: la entrada total crece en cada paso, aunque solo escribas una pregunta corta.

La pregunta en sí rara vez es lo que encarece. Lo que viaja con ella, sí.

Qué dispara los costes#

  • Sesiones largas en las que se reenvía una gran ventana de contexto con cada petición
  • Archivos grandes o bases de código enteras adjuntos, que viajan como entrada con cada mensaje
  • Muchas peticiones rápidas en poco tiempo
  • Usar un modelo de gama alta para tareas que uno más barato resuelve igual de bien

Consejos prácticos#

Primero mide. El gráfico diario y la tabla de sesiones del plugin muestran adónde van realmente los tokens. No puedes optimizar lo que no has mirado.

Evita el contexto innecesario. Los archivos grandes adjuntos «por si acaso» se suman a cada entrada. Adjunta solo lo que Claude necesita para la tarea actual.

Elige el modelo según la tarea. No todas las peticiones necesitan Opus. Las preguntas rápidas, las tareas de formato y los cambios de código sencillos suelen ir bien con Haiku o Sonnet por una fracción del coste. Compara la calidad y el coste total por tarea terminada, no solo el precio por token.

Entiende la caché. Un pico de C.Escritura al empezar una sesión es normal: se ha creado un contexto grande. Lo que importa es que después llegue C.Lectura. Si el mismo contexto se reutiliza en muchas peticiones, el coste inicial de escritura se amortiza rápido y el coste efectivo por petición baja mucho.

Usa el panel. El panel HTML (se abre con el botón de gráfico de la barra lateral) muestra tu historial de uso, 30, 60, 180 o 360 días con el selector de periodo de la cabecera, además de la distribución de modelos y la tendencia de la eficiencia de la caché. Mirar los datos a lo largo de varios días revela patrones que la vista de una sola sesión no muestra.

Preguntas frecuentes y solución de problemas#

¿Funciona en macOS y Linux, o solo en Windows? En todas las plataformas: el núcleo del plugin siempre ha sido independiente de la plataforma. El único detalle propio de una plataforma es dónde guarda sus sesiones el modo agente de Claude Desktop, una particularidad de Windows; la explicación completa está en Fuentes de datos y transparencia.

«Esta sesión» muestra más tokens que «Hoy», ¿es un error? No. Una sesión de Claude Code puede pasar de un día a otro, ver las tres vistas temporales más arriba.

¿Por qué mis anillos de 5 horas y de la semana están en gris, sin porcentaje? Desde la 2.5 el plugin solo muestra un porcentaje de límite si viene de Anthropic. Para ello hace falta el feed opcional. Sin él, los anillos muestran los tokens contados y el tiempo hasta el reinicio, y una línea corta debajo enlaza con la configuración. Con una consulta a horas fijas, unas pocas veces al día, el anillo de 5 horas sigue en gris la mayor parte del tiempo, porque una lectura de 5 horas solo vale dentro de la ventana en la que se tomó. Una consulta cada hora con --only-when-active lo cambia. Ver Límites: porcentajes solo de Anthropic.

¿Por qué la tarjeta «Limit Health» del panel no muestra ningún valor? Por la misma razón: necesita un valor semanal oficial del feed. Mientras no lo haya, la tarjeta remite a la configuración en lugar de adivinar.

¿Adónde ha ido el límite estimado? Se eliminó en la 2.5 porque fallaba demasiado: en la ventana de 5 horas se desviaba de media 36 puntos de los valores oficiales. Lo que queda es el rango en el que tu ventana de 5 horas se ha llenado hasta ahora.

El chat del navegador (claude.ai) o el chat normal de la app de escritorio no aparece en ningún sitio. Es lo esperado, no un error: ver Qué se mide y Fuentes de datos y transparencia más arriba.

La revisión de plugins de Obsidian marca «Direct Filesystem Access». ¿Debo preocuparme? No, ese aviso es esperado e inevitable para lo que hace este plugin; qué se lee y qué no está detallado en Fuentes de datos y transparencia.

Las cifras de un día cambiaron después de actualizar el plugin. ¿Se han corrompido datos antiguos? Casi seguro que no: ver la reconstrucción única en Archivo y datos a largo plazo.

¿Puedo seguir más de un vault de Obsidian o repartir el uso por cliente? Sí, ver Panel e informes por vault y proyecto.

¿Necesito una clave de API o una cuenta de Anthropic para usar este plugin? No. Lee archivos locales que Claude Code ya escribe en tu propio equipo.

Cerré Obsidian unas semanas. ¿Ese consumo se ha perdido para siempre? Si salió de tu periodo de retención de datos de Claude mientras Obsidian estaba cerrado, sí: ver el recuadro sobre el límite honesto en Archivo y datos a largo plazo.

Compatibilidad y actualizaciones de Claude Code#

Token Usage lee los archivos de sesión JSONL que Claude Code escribe en local. Anthropic actualiza Claude Code con regularidad, a veces de un modo que afecta a cómo se registran los datos de sesión o cómo se cuenta la telemetría interna.

Revisamos las notas de versión de Anthropic con cada versión importante de Claude Code y adaptamos el plugin cuando hace falta. Los cambios de compatibilidad relevantes se documentan en el registro de cambios del plugin en GitHub.

Sobre este plugin#

Token Usage es un plugin de código abierto de la comunidad de Obsidian. Lee archivos JSONL locales escritos por Claude Code; no se envía ningún dato a ningún sitio. ¿Echas algo en falta en esta página? Los issues y las propuestas son bienvenidos en cualquier momento.

Los precios citados en esta página proceden de la documentación oficial de Anthropic. Última actualización: octubre de 2026. Los precios pueden cambiar; consulta siempre las tarifas actuales en la web de Anthropic.