Token Usage

Token Usage

Changelog

What was added in which version, newest first. Each entry records what shipped at the time.

Older entries may contain statements that later versions corrected, mainly about the limits. The corrections are listed under 2.0.0 and 2.1.0.

2.1.0October 2026

Release on GitHub → (opens in a new tab)

Six things in this plugin were wrong, and two of them were claims we made ourselves in the 2.0.0 notes below. All six are corrected here. Your numbers will change after updating, mostly downward, and this is why.

Corrections

  • Long responses were counted many times over. Claude Code writes a single response to its session log once per content block, and for long streamed output up to about 75 times, each line repeating the full token counts of that one response. The plugin added up every line, so one reply of 7.7K output tokens showed up as roughly 580K. In a measured 30-minute stretch the sidebar displayed 1.31M tokens against a real 70K: the 5-hour ring jumped to 448%, Today to 330%, This Week to 114%, although nothing out of the ordinary had happened. Each response is now counted exactly once, identified by its message ID and request ID, and the line with the highest output count wins. Short replies were affected too, at about a factor of two, so your figures may be a little lower after updating. Because the 5-hour estimate is derived from the same counts, it may shift slightly as well
  • Subagent work was never counted. When Claude Code runs subagents (the Agent tool), it writes their work into a subfolder of the session. The plugin never looked there, so those tokens were missing from every figure. On our own data that was 0.7% of the last 30 days, but up to 47K tokens inside a single 5-hour window that hit its limit. Subagent logs are now read and counted with the session they belong to
  • Cache does count. We were wrong about this in 2.0.0. The 2.0.0 notes say cache reads and writes do not count toward a limit, "verified against 80+ observed limit hits". That analysis ran on the inflated totals of the first error above, so it could not show what it claimed. Measured since against the official percentages Claude Code reports: cache writes clearly count toward the 5-hour window, cache reads a little. One example from our own data: a long session that had to rebuild its cache after a pause took 17% of a fresh window on just 4.4K input and output tokens. The plugin's figures still count input and output only, so the official percentage can run ahead of them, most of all at the start of a window. The glossary entry and help section "What counts toward a limit" are rewritten
  • The weekly estimate could sit far too low. It is the lowest week that ever hit the weekly cap. On our own data that was 1.14M tokens against about 2.7M implied by the official percentages, and the sidebar showed 141% while Claude Code said 61%. Cache use that the plugin does not count also drives you into the cap, so a week can end at a low token figure. Without the new status line feed (below) the estimate still comes from your hits, and the help says plainly that it can be too low. With the feed, the official figure is used
  • "29-day average" was not what we computed. The 2.0.0 notes and the dashboard say Today is compared against your 29-day average. Since 1.7 the plugin has in fact used every day Claude Code keeps on disk (your retention setting). The labels now say so; the calculation stays
  • Cache prices in the help were incomplete and partly out of date. We wrote that a cache write costs about 1.25× the input price. That is the 5-minute cache; the 1-hour cache costs 2×, and it is the usual kind for Claude Code on a subscription (about 90% in our own logs). Cache reads cost 0.05× rather than 0.1× on Opus 5.5 and Sonnet 5.5. The price table on the help page also lacked the newest models and still called the Sonnet 5 price introductory. A user in the Obsidian forum pointed out the 1-hour cache in October, and we promised this correction for 2.1. Glossary, README and help now follow the official pricing page as of October 2026

Changed

  • The Today ring is neutral grey. There is no daily limit, and green, amber and red next to two real limits read like a warning. A busy day is a change in how you work, not a risk. The dashboard panel names the multiple instead ("2.5x your usual day")

New

  • Optional: limits anchored on the official percentages. Claude Code passes the official 5-hour and weekly percentages to any status line script. A small script shipped with this release (extras/ratelimit-statusline.js) shows them in your status line and logs them on your machine. When that log exists, the 5-hour window starts when the official window starts, and both limit rings show exactly the official percentage at every reading, then count on with your tokens until the next one. Without the script nothing changes. Setup: see the help page, section "Official percentages from your status line", or the README section of the same name
  • Glossary entry "Today ring", and "What counts toward a limit" rewritten, in all five languages
  • C.Write tooltip with the 1-hour and 5-minute split. Hover over any C.Write row to see how much of it was written for one hour and how much for five minutes. We looked at splitting the row itself and decided against it: the sidebar has no room for a fifth row, and the plugin does not compute costs

Known limits

  • Between two readings the plugin adds input and output only. A cache rebuild (new chat, expired cache) appears with the next reading
  • Archived days older than your retention window keep their old figures: the logs needed to recount them no longer exist. Days still inside the window are rewritten once after updating
  • Whether 1-hour and 5-minute cache writes weigh differently on the limit is still open. In every segment we could measure, the cache writes were all of the 1-hour kind, so a separate weight for the 5-minute kind cannot be determined yet. We keep measuring
Back to top

2.0.0October 2026

Release on GitHub → (opens in a new tab)

Three things this plugin believed about Anthropic's rate limits were wrong. All three are corrected here, which is why your numbers may look different after updating.

Corrections

  • There is no daily limit. Earlier versions measured Today against "a fair daily share" of the weekly cap — a number the plugin invented by dividing the weekly limit by seven. Anthropic enforces no such limit, so that comparison held a real day against an imaginary budget. Today is now shown against your own 29-day average per active day: it claims no quota, it tells you whether today is busier or quieter than usual. *(Partly wrong: it was never 29 days but every stored day. Corrected in 2.1.0.)*
  • The 5-hour window is anchored, not rolling. It opens with your first message and runs exactly five hours; a new window only starts once that span has fully elapsed, chained in fixed blocks regardless of pauses in between. Previous versions summed "the last five hours from now", which at a window turnover mixed the tail of the old window with the head of the new one — a figure that belonged to neither, precisely when you most wanted to see that your budget had reset
  • Only input and output count toward a limit. Cache reads and cache writes do not. This was verified against 80+ observed limit hits rather than assumed: a weighted model was tested, and the weights that best explained the real data were zero for both cache types. The resulting median 5-hour budget matches what users actually observe. *(Wrong: the analysis ran on double-counted totals, and cache writes do count. Corrected in 2.1.0.)*

New

  • Activity heatmap built around your billing week — one row per calendar day, twelve 2-hour bubbles per row, spanning your actual weekly window from reset hour to reset hour. Because that window touches eight calendar dates, the view shows eight rows, with the cells outside the window visibly inactive. Collapsible, with an Active Days panel beside it
  • The weekly reset detects itself. The weekly limit resets at an hour that differs per account. The plugin now calibrates that hour from your own session history instead of asking you to guess it, and says in Settings whether the value was detected or set by hand
  • CSV export, two ways — from the sidebar header into a configurable vault folder, or via the command palette. Three files (projects, daily detail, key figures), RFC 4180 with a UTF-8 BOM so Excel opens them correctly on the first try
  • 5-hour estimate with a usual band — the sidebar and the dashboard show the median and the middle half of your observed hits (for example "usually between 214K and 364K"), and the CSV export carries both ends. The estimate itself is now measured inside the anchored 5-hour windows, the same way the gauge counts, so the two are directly comparable; numbers may therefore shift slightly after updating.
  • Calendar shows two months instead of one, so the start of a month is no longer a nearly empty grid
  • Spanish — the plugin UI and the full glossary are now available in Spanish, alongside English, German, French, and Italian

Changed

  • New look — the colour world has been rebuilt around one rule: a colour either identifies a token type or signals status, never both. Previously the same green could mean "output tokens" in one panel and "you are fine" in the next
  • The Classic sidebar has been removed. What was opt-in as "NextGen" is now simply the sidebar; the Sidebar appearance setting is gone
Back to top

1.9.0September 2026

Release on GitHub → (opens in a new tab)
  • Dashboard: Limit Hero banner — the empirical session, daily-pacing, and weekly limit estimates now get a prominent banner at the very top of the dashboard, above the KPI cards, instead of being buried in a KPI card and a data table further down
  • Sidebar: Limit Pulse (NextGen) — the same Today-vs-fair-daily-share and this-week-vs-estimated-weekly-limit numbers now sit at the very top of the Today page too, so you see them the moment you open the sidebar, no dashboard needed. Same underlying calculation as the Dashboard's Limit Hero — the two can never show different numbers
  • Activity calendar: bigger hover target — the tooltip now lives on the whole day cell, not just the small colored dot, making it much easier to hit with the mouse
  • Activity calendar: per-day notes — click any day to add a short personal note about that day's usage. Purely local, stored in plugin settings, shown as a small marker on the day and in its tooltip
  • Cross-platform clarity — Token Usage already worked fully on macOS and Linux: the core session reading has always been platform-neutral (~/.claude/projects/ via Node's os.homedir()), no code change was needed there
  • Agent Mode discovery correctly scoped to Windows — the Claude Desktop Agent Mode session finder added in v1.8.0 turned out to be a Windows-only necessity, since only the Windows app runs its embedded Claude Code inside an MSIX sandbox that virtualises the filesystem. On macOS/Linux, Agent Mode sessions already land in the same standard ~/.claude/projects/ location the plugin already reads — no extra path guessing needed or added there
  • Removed a briefly-added, unverified Windows-Store-style path guess for macOS, replaced with a documented, evidence-based platform boundary in the code (see claude-dev.tools/docs/log-locations (opens in a new tab) for the underlying reference)
  • Documentation updated with an explicit note on where session data lives per platform
Back to top

1.8.0September 2026

Release on GitHub → (opens in a new tab)
  • Activity calendar (NextGen sidebar) — a month grid pinned to the bottom of every rail page, one colored dot per day sized against your own recent daily average (green below, amber around, red for a 2×+ spike). Navigate back through your history; toggle it off under Settings → Activity calendar
  • Claude desktop app usage now counts — the agent mode built into the desktop app runs Claude Code and writes the same JSONL session logs to its own location; the plugin now reads those too, so that consumption no longer goes missing from your totals and rate-limit estimates. A one-time archive rebuild on first launch backfills the affected days
  • Dashboard: expandable sub-project detail — the Projects view stays one row per vault by default; tick "Show sub-project detail" to expand any vault and see its per-subfolder token split inline, not only in the Markdown export
  • Clearer scope — a new "What is measured" glossary entry and dashboard note make explicit that the plugin covers Claude Code everywhere, but not ordinary Claude chat (which writes no local token counts)
  • Manual — a chapter-by-chapter guide is taking shape at langeatn.de/media/token-usage/manual/; the outline is live, content fills in over the coming releases
Back to top

1.7.1September 2026

Release on GitHub → (opens in a new tab)
  • NextGen sidebar (opt-in, Settings → Sidebar appearance, Classic sidebar unchanged by default) — icon rail navigation (Today / Overview / Settings), a 7-day activity heatmap, and colored KPI tiles with trend sparklines
  • Vault Token Usage Controlling — the Dashboard's new Projects view breaks token usage down by vault and sub-project, so you can track and compare consumption across multiple vaults (e.g. separate client workspaces) from one place. Sortable overview and day-by-vault detail tables (click any column header, "today first" default), plus a standalone Vault_Token_Usage_Projects.md export for billing
  • Redesigned Dashboard — 5 KPI cards (weekly forecast, limit health, cache efficiency, daily velocity, focus score), a week status bar with on-track forecast, a period dropdown (30/60/180/360 days), and a new Reports tab
  • Historical reporting beyond 30 days — daily usage is now archived directly in your vault, so 60/90+ day views keep working even after Claude Code rolls off its own local logs
  • Configurable Claude data retention — control how long the original session log files are kept on disk, right from the plugin settings
  • In-app "What's new" popup — after updating, a short summary of the latest changes appears once. Reopen it anytime via Command Palette → "Show what's new"
Back to top

1.6.0August 2026

Release on GitHub → (opens in a new tab)
  • Multilingual UI — English, German, and French. Language dropdown in Settings switches immediately without restart. French translation reviewed by a native speaker.
  • Settings button (⚙) in the sidebar header — opens the plugin settings tab directly without navigating through the Obsidian menu
  • Rate limit auto-detection — session and weekly limit hits are now read automatically from Claude Code's local JSONL files. No manual button needed. The plugin detects the exact moment a limit was reached and which type it was (session vs. weekly)
  • Dashboard: Rate limits section — table of all detected limit events with the relevant token metric at the time of the hit (5h window for session limits, full billing-week total for weekly limits), plus empirical estimates for session and weekly limit thresholds derived from your own usage history
  • Dashboard: Weekly consumption chart — 6-week bar chart aligned to Claude's billing week boundary (Sunday 18:00 → Sunday 18:00 Europe/Berlin), with visual highlight for weeks where the weekly limit was reached
  • Spike warning — amber badge next to Today when daily consumption is ≥ 2× your personal 29-day average (active days only)
  • Last Action chips — four colored chips (In / Out / C.Wr / C.Rd) replace the plain-text row in the Last Action section, consistent with the minibar color scheme throughout the sidebar
  • Collapsible sections — all five time-range sections can be collapsed individually with a click. State persists across data refreshes
  • Window cleared indicator — shows "Window cleared · full 5h available" in green when the 5h window is empty but activity was recorded in the past 6 hours
  • Bugfix — zero-token entries are now filtered from the 5h window and no longer affect the countdown or display
Back to top

1.5.0August 2026

Release on GitHub → (opens in a new tab)
  • Context sub-labels under each section title — shows exactly what each time range covers at a glance ("Rolling window · counts toward rate limit", session start time, "Calendar day · since midnight")
  • ← Back button in the glossary header — returns to the data view without hunting for the ? button
  • Logarithmic minibar scale — all four token types (Input, Output, C.Write, C.Read) stay visually readable even across large magnitude differences
  • Sticky header — logo and buttons stay pinned when the panel is small or scrolled
  • Bugfix — C.Write bar was invisible due to a missing CSS class (.au-bar-purple)
  • New glossary entry — "The three time views" explains how Last 5 Hour Session, This Session, and Today are independent cuts through the same data
  • GitHub artifact attestations — release assets are now cryptographically signed
Back to top

1.4.1August 2026

Release on GitHub → (opens in a new tab)
  • Redesigned logo header with SVG chart icon and gradient text
  • Built-in glossary panel — toggle with the ? button, explains all token concepts and includes an approximate cost reference
  • HTML dashboard — 30-day charts, model donut, top sessions table, cache efficiency analysis
  • C.Write and C.Read split into separate rows throughout the sidebar
  • 7-day stacked model distribution bar (Haiku / Sonnet / Opus / Fable)
  • Help page at langeatn.de/media/token-usage/ (English and German, auto-detected)
Back to top

1.0.0 – 1.0.2July 2026

Release on GitHub → (opens in a new tab)
  • Initial release
  • Live file watcher on active Claude Code session
  • Token breakdown across Last Action, This Session, Today, 7 Days, 30 Days
  • Fallback polling interval (configurable)
  • Approved and listed in the Obsidian Community Plugin Directory
Back to top

Source: the changelog in the project README. To the project page →