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, 2.1.0 and 2.5.0.

2.5.1November 2026

Release on GitHub → (opens in a new tab)

A patch for two mistakes of ours: the sidebar made Obsidian freeze while Claude Code was busy, and our poll guide for Windows opened a console window every 30 minutes.

Fixed

  • Obsidian froze for seconds while Claude Code was busy. On every refresh the sidebar read and parsed all session logs in Claude Code's retention window again, on Obsidian's main thread, and smaller files even twice. The file watcher started such a refresh after every write to the session log, and a busy session writes many times a minute. On our own machine (245 log files, 1.1 GB, 120 days of retention) one refresh took about four seconds and came every four to six seconds, so Obsidian stood still most of the time. The longer your history and the busier your session, the worse it got, and with Claude Code running inside Obsidian it was at its worst. That was our mistake, and we had not noticed it before. Now each log is parsed once and kept in memory: unchanged files are not read again, and a log that grew is read only from where the last read stopped. Measured on the same machine: about 110 ms per refresh instead of four seconds. Only the first refresh after starting Obsidian still reads everything, once
  • Our Windows guide for the poll opened a console window on every run. The Task Scheduler commands started node.exe directly. node.exe is a console program, so Windows opened a window every time, with the recommended variant every 30 minutes, even on runs that asked nothing. The guide now starts it through conhost.exe --headless, which keeps the window away, and has one block that switches an existing task over without changing anything else. We tested this on Windows 11. Microsoft does not document this switch, and some security software reports hidden console starts as suspicious; for that case the plain start stays in the guide

Changed

  • While a session is busy, the sidebar refreshes at most every 30 seconds. Up to 2.5.0 every write restarted a short wait of 0.6 seconds, so a busy session set off one refresh after another. The first response after a quiet spell still shows up after 0.6 seconds; while writes keep coming, the next refresh follows at the latest 30 seconds after the previous one and includes everything written until then. The refresh button and the interval in the settings are not throttled
  • The settings text no longer says the file watcher reacts immediately to every response, in all five languages. With the 30-second limit that is no longer true; it now says "within 30 seconds at the latest". The help page says the same
  • Every hour is enough for the poll that runs only while you work. We recommended every 30 minutes. That is twice the requests for a reading that is at most half an hour fresher. The guide, the cron line, the script header and the help page now say every hour
Back to top

2.5.0October 2026

Release on GitHub → (opens in a new tab)

Percentages now come from Anthropic only. This is the biggest change since 2.0, and it starts with a decision of ours that was wrong. The version jumps from 2.1 to 2.5 to make that visible.

Changed

  • Percentages come from Anthropic only. Up to 2.1, Token Usage estimated a percentage for the 5-hour window and for the week, either from your own limit hits or extrapolated from the feed. We put that estimate next to the official figures for eleven days. For the 5-hour window it was off by 36 points on average, and at the moment a window was officially full, our ring stood anywhere between 61 and 217 percent (our own measurement, 37 readings, 6 to 17 October 2026). How fast a window fills up depends heavily on how much context a session carries along, and the local logs cannot tell that reliably. The rings suggested a precision they never had. That was our decision, and it was wrong. From 2.5 on, one simple rule applies: we only show a percentage for a limit when it comes from Anthropic, together with the time it was read. For that you need the feed (setup on the help page). We make one exception for the week: between two readings we carry the last official figure forward with your counted tokens and label it as such, because the weekly limit proved stable in the same measurement (1.2 points off on average). Without the feed you see what we know for certain: your tokens in the current window and in the week, the time until the reset, and the range at which your 5-hour window has filled up so far
  • The Today ring shows a multiple, not a percentage. "1.5x your usual day" instead of "150%", so every percentage on screen either comes from Anthropic or is a labelled weekly projection from an Anthropic value
  • The heatmap measures each cell against your own usual 2-hour block (the average of your active 2-hour blocks over the stored days, named under the grid). Up to 2.1 it was measured against the estimated 5-hour limit, which no longer exists
  • The span instead of an estimate. Under the rings: "Your 5h window has filled up after 51K to 316K so far (102 limit hits)". It replaces the old line "5h limit estimated at X, median of n hits" and shows how wide that range really is
  • Dashboard and CSV exports follow the same rule. The budget panels, the overall zone, the Limit Health card and the week bar use official values only; without them the panels show counted tokens and the time to the reset. The rows for estimated limits in both CSV exports are replaced by the official values with the time of the reading, the labelled weekly projection, the weekly limit the feed implies, and the span

Security

  • The dashboard put folder and model names into the page unescaped. The project name in the dashboard is the last folder of the working directory a session started in. A crafted folder name, for example of a cloned repository, could have run script inside the dashboard page in your browser; a model name containing </script> could break the whole page. The dashboard opens as a local file in the browser, without access to your other files or to Obsidian, but such a script could have sent the dashboard figures elsewhere. All names are now escaped, the sort headers no longer carry names in inline handlers, and the embedded data can no longer close its script block. We found this in our own security check in October 2026, have no indication it was ever used, and added a test that runs the real dashboard with crafted names. The sidebar inside Obsidian was not affected: it never put names into HTML
  • CSV exports neutralise formulas. A text cell starting with =, +, - or @ (for example a folder name) would have been run as a formula by Excel or LibreOffice. Such cells now start with an apostrophe; plain numbers stay as they are
  • The release workflow pins its actions to fixed commits instead of version tags that can be moved, and no longer keeps a token in the checkout

Fixed

  • The weekly reset was an hour off after the switch to winter time. Anthropic resets at a fixed moment in UTC. The plugin stored it as a local weekday and hour, so after the clocks changed every week boundary sat an hour off for half the year. The reset now comes from the feed or from your weekly-limit message as an exact moment, and the week steps on from there. A reset you set by hand stays in local time. The dashboard also no longer assumes Sunday 16:00 UTC for everyone, which was one account's schedule
  • Usage credits inflated the weekly limit derived from the feed. With usage credits, work goes on after the weekly limit. The plugin divided those extra tokens by the 100% reading, so the derived limit grew with every credit token. Readings at or above 100%, and anything after them in the same week, are no longer used; a week at 100% shows the official value without carrying it forward
  • The CSS lint note about :has from the community review is gone. We promised this fix for 2.1 in the forum and missed it twice
  • The glossary still said cache does not count toward a limit. That contradicted our own 2.1.0 correction, in the entry "Cost overview", in all five languages. Corrected
  • The trend lines of the 7-day tiles on the Analytics page were flat. The tiles read a daily figure that the 7-day series never delivered: Calls and Active Days from the start, Total and Avg per active day since 2.0. The 30-day tiles were not affected. We only noticed it on the new store screenshots for 2.5; the 2.0 screenshots already showed it

New

  • Further official windows are shown when Anthropic reports them, for example a separate weekly limit for one model. Both feed scripts now record such windows; the plugin estimates nothing for them
  • The poll script tries once more after a timeout. A scheduled run right after the computer wakes from sleep often has no network yet
  • The poll script can run only while you work. With --only-when-active it asks only if Claude Code wrote to its logs in the last 20 minutes. A 5-hour window is open then anyway, so the script practically never opens one itself and can run every 30 minutes. With three fixed polls a day the 5-hour ring stayed grey most of the time; we noticed that in our own test before the release
  • A hint under the rings when there is no feed, with a link to the setup
  • Percentage and tokens, explained. The tooltips of the 5-hour and weekly rings and the note above the Dashboard panels now say why the two do not match directly: the tokens count input and output, Anthropic also counts the context a session sends along
  • The help page is rebuilt and now also in Italian. One layout for English, German, French, Spanish and Italian, the same sections in every language, a contents bar beside the text. Up to 2.1 the German and French pages lacked four sections, the Spanish page was a shorter text of its own, and all pages still named the model colours from before 2.0

Known limits

  • Without the feed there are no limit percentages at all. In clients without a status line, such as Obsidian, readings come from the scheduled poll, which is a tiny real request each time and opens a 5-hour window if none is open
  • With a poll at fixed times, a few times a day, the 5-hour ring is grey most of the time: a 5-hour reading only counts inside the window it was taken in. The poll only while you work (see New) avoids that
  • In 2.1.0 we listed as open whether 1-hour and 5-minute cache writes weigh differently on the limit. It stayed unmeasurable: in every segment up to 17 October the cache writes were practically all of the 1-hour kind. Since 2.5 the plugin estimates no limits, so this question no longer affects any figure it shows
Back to top

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. *(Removed in 2.5.0: measured against the official values, the estimate was off by 36 points on average. Percentages now come from Anthropic only.)*
  • 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 →