Understanding Token Usage
in Claude Code

Contents

• Getting Started
• Data Sources & Transparency
• Rate Limit Estimates
• Core Concepts (tokens, caching, the Reuse Factor, Focus Score, models, sessions)
• What Counts Toward a Limit
• Today Ring
• Official Percentages from Your Status Line
• The Sidebar, Heatmap & Calendar
• Exporting Your Data (CSV)
• Archive & Long-term Data
• Dashboard & Vault/Project Reporting
• Settings Reference
• API Pricing Reference
• Costs, Drivers & Practical Tips
• FAQ & Troubleshooting
• Compatibility & Updates
• About This Plugin

Getting Started

Install. Inside Obsidian: Settings → Community plugins → Browse → search "Token Usage" → Install → Enable. That's the entire setup — no account to create, no API key to paste in, no external service to sign up for. Works the same way on Windows, macOS, and Linux — see Data Sources & Transparency for the one platform-specific detail (Claude Desktop's Agent Mode session location).

Open it. Click the bar-chart icon in the left ribbon, or run "Open Token Usage" from the Command Palette (Ctrl/Cmd+P). Either opens the view in the right sidebar, where it stays like any other Obsidian pane.

Nothing to configure to get useful numbers. The sidebar works immediately: an icon rail on the left with four pages — Today, Calendar, Analytics and Settings — see below. Since 2.0 there is only this one layout; the older "Classic" view and the setting that switched between them are gone.

Commands available from day one (Command Palette):

Command	What it does
Open Token Usage	Opens (or focuses) the sidebar view
Create Token Usage report	Writes a Markdown usage report into your vault
Open Token Usage dashboard	Builds the HTML dashboard and opens it in your default browser
Create Vault Token Usage Projects report	Writes a per-vault/per-project Markdown breakdown, handy for billing multiple clients or workspaces
Show what's new	Re-opens the highlights popup for the currently installed version, any time
Export all CSV files	Writes all three CSV exports into your vault — see Exporting Your Data
Export projects CSV	Vault/project overview as a single CSV
Export daily detail CSV	The day-by-vault matrix as a single CSV
Export key figures CSV	The headline numbers and limit estimates as a single CSV

Data Sources & Transparency

This plugin needs direct filesystem access to work at all — Obsidian's own Community Plugin review flags that as an expected warning, not a defect, since reading local session files is the entire point. Rather than ask you to trust that blindly, here is exactly where those files live, exactly which fields the plugin reads, and exactly what it never touches. Every claim below is verifiable directly in the plugin's own source: main.js is unminified and public on GitHub.

Where the JSONL files actually live. Claude Code — whether run from a terminal, inside an editor like VS Code, or from within Obsidian — writes one JSONL file per session under ~/.claude/projects/<workspace-id>/<session-id>.jsonl, one subfolder per working directory. This is identical on Windows (C:\Users\<you>\.claude\projects\...), macOS (/Users/<you>/.claude/projects/...), and Linux (/home/<you>/.claude/projects/...) — the plugin resolves it via Node's os.homedir(), which is platform-neutral by design, so this part has always worked the same way everywhere. One more file is involved, read-only unless you actively use the in-plugin retention control: Claude Code's own ~/.claude/settings.json, checked purely for the cleanupPeriodDays value — if you change it from plugin settings, a .bak backup of the whole file is written automatically first.

Claude Desktop Agent Mode — a Windows-only exception, as of today's evidence. The Windows build of the Claude desktop app runs its embedded Claude Code inside an MSIX app-container sandbox, which virtualises the filesystem — so Agent Mode sessions there physically land somewhere other than the ordinary path above: %APPDATA%\Claude\local-agent-mode-sessions\..., or for the Microsoft-Store-packaged build, the sandboxed %LOCALAPPDATA%\Packages\<package-id>\LocalCache\Roaming\Claude\local-agent-mode-sessions\.... The plugin has walked this second location automatically since v1.8.0, on Windows only. macOS and Linux have no equivalent app-container sandboxing layer, and per available documentation, Claude Code — CLI, editor integrations, and the desktop app alike — writes to the same ~/.claude/projects/ on every platform. So on macOS/Linux, Agent Mode sessions (where the feature exists) are expected to already land in the standard location the plugin reads by default, with no extra code needed. This is the current best evidence, not an Anthropic primary source — if you use Claude Desktop's Agent Mode on macOS or Linux and notice usage that doesn't show up, please open a GitHub issue.

Field read from a session line	What it is used for
message.usage	Input / output / cache-write / cache-read token counts — every number in the sidebar and dashboard
message.model	Which model the row belongs to (Haiku / Sonnet / Opus / Fable)
cwd, sessionId	Which vault, sub-project and session a data point belongs to
timestamp	When — drives every time-based view, the 5h window, and the archive
compactMetadata (system entries)	Pre-/post-compaction token counts, shown as compaction events
error (system entries)	Rate-limit and connection-failure detection only — never message content
aiTitle	The one exception below

The one thing that isn't a number. Claude Code itself writes a short, auto-generated title for each session into the same JSONL file (an ai-title entry). The dashboard's Top Sessions table reads that single short string and shows it in place of a raw session UUID, purely so the list is readable. It is the only field this plugin surfaces that is derived from conversation content rather than pure usage numbers — Claude Code's own summary, not anything the plugin generates or expands on.

What leaves your machine: nothing. No network requests, no telemetry, no external server — every number is computed locally. The plugin writes exactly two kinds of new files, both inside your own vault, both aggregate-only: the daily archive under Token Usage Archive/ (see Archive & Long-term Data) and, only when you actively trigger it, the Markdown report, HTML dashboard, and vault/projects export. None of the three ever contain a prompt or a response.

If you want to check the browser yourself. Your browser's own developer tools (F12 → Network tab, filtered to XHR/Fetch) will show every request while you use claude.ai. Two honest caveats: this plugin does none of that for you — no browser integration, no extension, no proxy, a deliberate boundary rather than a missing feature. And claude.ai's web client talks to Anthropic's internal, undocumented endpoints, not the same as the public Claude API that Claude Code uses — so any token-like numbers visible there are internal implementation details that can change without notice, not a documented data source. The public API's usage object, the one Claude Code writes to your local JSONL files and the one this plugin actually reads, remains the only stable, documented source of exact token counts.

Rate Limit Estimates — A Number Anthropic Never Publishes

Anthropic doesn't publish the actual token limit behind a rate-limit hit — it exists server-side and stays invisible, both for the anchored 5-hour session window and the weekly cap. Token Usage makes it empirically visible instead: every rate-limit hit detected in your own local session files becomes a data point, and enough data points become an estimate of your own session and weekly limits. Not a guess, not marketing language — a number built from what actually happened on your account.

This estimate isn't a one-time snapshot. It quietly gets more precise the longer you use Claude Code — every new rate-limit hit refines it further, so the number you see today is more reliable than the one from your first week. Because it is built entirely from your own local data, there is nothing to configure and nothing to opt into: the estimate simply improves on its own as you keep working.

You'll find the current estimate in two places: the dashboard's budget banner right at the top, and the sidebar's Right Now section with its three rings (5h window, today, this week). The line beneath the rings names the 5-hour estimate outright and says how many observed limit hits it rests on. Both surfaces read from the exact same calculation, so they can never disagree.

The 5-hour estimate is shown as a median together with a usual band: the middle half of your observed hits. The same limit is rarely reached at exactly the same total, because other Claude use that Token Usage cannot see (such as claude.ai in the browser) draws on the same limit, so a single number alone would look more precise than it is. Each hit is measured inside its own anchored 5-hour window, exactly the way the ring counts, so the two are directly comparable. In the sidebar the band sits on its own line beneath the estimate; in the dashboard it replaces the former min-max range in the budget banner, and the CSV export carries both ends.

What is a Token?

A token is a small chunk of text — roughly three quarters of a word in English. It is not exactly a word and not exactly a character. The sentence "Good morning, how are you today?" breaks into roughly 7 tokens. Longer or unusual words may cost more; common short words often share one. Both your input and Claude's response are counted, separately.

Input and Output

Input is everything Claude receives in a single request: your message, the system prompt, file contents, tool results, and the conversation history re-sent with each new turn.

Output is what Claude writes back. Output tokens are consistently more expensive than input tokens across all models — typically 3–5× more.

A single question is cheap. The costs grow with volume, context size, and repetition — not with the complexity of what you ask.

C.Write — Cache Write

When Claude Code sends a large, repeated block of text (project files, a long system prompt, an entire codebase), Anthropic's infrastructure can cache it. The first time that block is processed, it is written into the cache. This is a cache write.

There are two kinds of cache write, priced differently: a 5-minute cache write costs 1.25× the standard input price, a 1-hour cache write costs 2×. In our own logs about 90% of the cache writes from Claude Code on a subscription were the 1-hour kind, while subagents wrote 5-minute caches. Since 2.1.0, hovering over a C.Write row in the sidebar shows the split for that period. It is an investment: you pay more upfront so that subsequent requests can skip reprocessing the same content. Cache writes also count toward the 5-hour limit, see What Counts Toward a Limit.

The plugin displays C.Write in aqua throughout the sidebar.

C.Read — Cache Read

Once a block is cached, Claude can read it from the cache on subsequent requests instead of processing it from scratch. This is a cache read.

Cache reads cost only a fraction of the standard input price: 0.1× on most models, 0.05× on Opus 5.5 and Sonnet 5.5, 0.025× on Fable 5.1. If the same context is used many times, cache reads make large sessions significantly more affordable than they would otherwise be.

The plugin displays C.Read in violet to signal high volume but low cost per token.

C.Write vs. C.Read — The Reuse Factor, and What It Tells You About How You Work

The relationship between these two numbers is more than a cost detail — it is a direct, honest readout of whether a stretch of work was focused or scattered.

Reuse Factor	What it signals
≥ 8×	Deep focus — excellent cache return, the same context is carrying many requests.
3–8×	Balanced — focused work with some variety mixed in.
1–3×	Exploratory — frequent new context, typical of research or scoping work.
< 1×	Minimal reuse — mostly independent, short, one-off sessions.

High reuse means you kept returning to the same context with follow-ups instead of constantly starting over; low reuse means near-constant context switching. Neither is "wrong" — exploration has its place — but if your goal was deep, sustained work and the Reuse Factor says otherwise, that's worth noticing. The dashboard shows this ratio in the Cache Efficiency section, including a line chart with C.Write in aqua and C.Read in violet — matching the sidebar colors.

Focus Score — a second, independent signal. The dashboard's Focus Score (0–100) combines three things the plugin can already see: cache reuse (the Reuse Factor bands above, 50% of the score), continuity (fewer, longer sessions per active day score higher than many short ones, 30%), and depth (more back-and-forth turns per session score higher than one-shot exchanges, 20%). The result maps to a badge — Deep Work Mode (80+), Focused (60+), Balanced (40+), or Scattered (below 40).

For beginners: the single highest-leverage habit is staying in one continuous session for one continuous problem, and asking follow-ups instead of restating context in a new message — that alone tends to lift both numbers, and is usually just a better way to work. For experienced users: a consistently low Reuse Factor across a whole project might mean the system prompt or shared context is being rebuilt every time rather than reused — worth fixing at the workflow level (longer-lived sessions, a shared reference file, sub-agents that inherit context) rather than accepted as the cost of doing business.

Current 5h Window

Claude Code enforces a 5-hour window, and it is anchored, not rolling. The window opens with your first message and runs exactly five hours; a new one only starts once that span has fully elapsed, chained in fixed five-hour blocks regardless of how much idle time falls in between. It is not "the last five hours counted backwards from now" — and it is independent of the weekly reset, which runs on its own schedule and does not also start a fresh 5-hour window.

The plugin reconstructs those real windows from your activity and sums the one that is currently open, showing Input, Output, C.Write, and C.Read as separate rows. This matters at the moment a window turns over: a rolling calculation would add the tail of the window that just closed to the head of the one that just opened, producing a figure that belongs to neither — exactly when you most want to see that you have fresh budget.

This is the most immediate view of your current session. If you have been working for a while without a long break, this window captures what you have spent since the window opened.

Why the countdown shows a tilde (~)

The reset countdown in the sidebar footer reads "Claude 5h resets in: ~Xh Ym". The tilde is intentional — it signals that this is an approximation, not an exact value.

Claude Code writes session data to local files after each response is fully completed, not at the exact moment you send your first message. When a session starts, the first request is often a long one — loading context, reading files, thinking. That first response can take 10 to 25 minutes. During that time, nothing is written to the local session log yet. So the earliest timestamp the plugin can read is not your actual session start — it is the moment your first response landed.

This means the plugin's countdown may run 10 to 25 minutes behind Claude's own display. For the precise reset time, check the plan usage section in Claude Code or on claude.ai. The plugin value is a reliable orientation, but Claude's own display is the authoritative source.

The three time views — how they relate

The sidebar shows three different summaries of your activity: Current 5h Window, This Session, and Today. These are three independent cuts through the same data — they do not automatically nest inside each other like hours, days, and weeks would.

View	What it covers	Resets when
Current 5h Window	Anchored window: everything since it opened	When it expires — the next message opens a fresh one, in fixed five-hour steps regardless of pauses
This Session	All entries with the current session ID, regardless of calendar date	When you start a new Claude Code session (new JSONL file)
Today	Calendar day: everything since midnight	Every day at midnight

The key implication: a session can span multiple days. If you started a long session yesterday and continued it today, "This Session" will show more tokens than "Today". That is expected — the session accumulates across calendar boundaries while "Today" only counts from this midnight.

Similarly, the 5-hour window is not a subset of "Today": a window that opened late yesterday evening reaches back across midnight, and everything in it still counts toward the same limit. Equally, the two can be identical — if your window opened this morning and you have not worked before that today, both figures show the same number until the window closes.

The plugin makes this visible: a small sub-label under each section title explains its scope. "This Session" shows when the session started, so you can immediately see whether the numbers span multiple days.

Models

Claude Code routes requests to different models depending on the task. The sidebar shows a stacked percentage bar of model distribution over the last 7 days, with each model family in its own color:

Model	Sidebar color	Typical role
Haiku	Cyan	Fast, lightweight tasks, lowest cost
Sonnet	Blue	Balanced capability and cost
Opus	Purple	Complex reasoning, demanding work
Fable	Amber	Highest capability, highest cost
Other	Gray	Unrecognized or future model strings

Knowing your model mix explains a lot of day-to-day cost variation. A day heavy on Opus looks very different in cost from a day spent mostly in Haiku. For the current model lineup and exact pricing, Anthropic's own pricing page is the source of truth — see also API Pricing Reference below.

Sessions

Claude Code writes one JSONL log file per session. The plugin reads all files under ~/.claude/projects/ and groups usage by session. The dashboard's Top Sessions table shows which individual runs consumed the most tokens — useful for spotting unexpectedly expensive sessions.

What Counts Toward a Limit

Anthropic enforces two limits and nothing else: the 5-hour window above, and a weekly cap that resets at a fixed weekday and hour. There is no daily limit — so the Today panel is not a quota (see Today Ring).

Input and output tokens count, and cache is not free either. Measurements against the official percentages Claude Code reports (October 2026) indicate that cache writes clearly count toward the 5-hour window and cache reads count a little. An earlier analysis of observed limit hits had pointed the other way. The newer measurements are more direct. The plugin's figures still count input and output only. When a long session has to rebuild its cache, for example in a new 5-hour window after a pause or when a large context is loaded for the first time, the official figure can therefore run ahead of the plugin. In practice: long sessions with a large context use up the 5-hour window faster per answer than fresh, short ones.

Neither limit is published. Both estimates come from your own history, which is why the plugin can only show them once it has seen you hit a limit at least once. Until then it says so instead of inventing a number. The weekly estimate from hits is the lowest week that ever reached the cap and can sit far too low, because cache use the plugin does not count also drives you into it. With the status line feed (see Official Percentages from Your Status Line) the plugin uses the official figures instead.

Today Ring

There is no daily limit. Anthropic only limits the 5-hour window and the week. The Today ring compares what you have used today with your own average per active day, taken over every day Claude Code keeps on disk (your data retention setting, cleanupPeriodDays).

200% means you are working twice as much as usual today, nothing more. A busy day is a change in how you work, not a warning. How close you are to a limit is shown only by the rings for the 5-hour window and the week. That is why, since 2.1.0, the ring stays neutral grey.

Official Percentages from Your Status Line

Optional, since 2.1.0. Token Usage works without it. Claude Code knows the official rate-limit percentages of your plan, the numbers /usage shows. Two small scripts from the plugin repository write them to ~/.claude/ratelimit-log.jsonl. When that file exists, the plugin anchors its rings on them. The complete guide is in the extras folder on GitHub.

What you gain

	Without a feed	With a feed
5-hour window start	Reconstructed from your first logged message	The official start, also when the window was opened on claude.ai, another device or another tool
5-hour ring	Your tokens against the median of your own limit hits	Exactly the official percentage at every reading, counting on with your tokens in between
Weekly ring	Your tokens against the lowest week that ever hit the cap, which can be far too low	Exactly the official percentage at every reading
Needs a limit hit first	Yes	No

Requirements

• A Pro or Max subscription that Claude Code is logged in with. With an API key there are no plan percentages.
• Node.js, because both scripts are small Node programs. Check with node --version. If it is missing, install the LTS version from the Node.js website. Claude Code installed with the native installer does not bring Node.js along.
• A recent Claude Code version, and for the poll the Claude Code CLI claude.

Which script do I need?

Where you work	Script
In a terminal	ratelimit-statusline.js as your status line. Free, readings come in while you work
Inside Obsidian, an editor or another client without a status line	ratelimit-poll.js, run on a schedule
Both	Both. They write to the same file

A status line only runs while Claude Code's interactive terminal is open. Clients that embed Claude Code do not run it, so the status line alone produces few or no readings there.

Option A: status line script

Copy the script to ~/.claude/ratelimit-statusline.js and add this entry to ~/.claude/settings.json, next to any keys that are already there:

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

On Windows use the full path with forward slashes, for example node C:/Users/<you>/.claude/ratelimit-statusline.js. Restart Claude Code; the status line then reads 5h 12% | week 34%. Already using a status line of your own? Keep it and add the logging part of our script to it.

Option B: scheduled poll

Before you set it up: every run is a real, tiny request (the prompt ok to Haiku, no session saved) and counts toward your usage. If no 5-hour window is open at that moment, the request opens one, so your next window starts at the poll time. Schedule it for times you work anyway; three times a day is plenty.

Copy the script to ~/.claude/ratelimit-poll.js and run it once by hand with node ~/.claude/ratelimit-poll.js. It prints 5h 12% | week 34%. Then schedule it.

Windows (PowerShell, runs at 12:00, 17:00 and 22:00 and catches up after the computer was off):

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

macOS and Linux (crontab -e, with full paths from which node and which claude, because cron runs with a minimal PATH):

0 12,17,22 * * * CLAUDE_BIN=/full/path/to/claude /full/path/to/node /Users/<you>/.claude/ratelimit-poll.js

On Linux the home folder is usually /home/<you>. Errors of scheduled runs go to ~/.claude/ratelimit-poll-errors.log. If the script cannot find the Claude Code CLI, set CLAUDE_BIN to its full path.

Check that it works

• The file ~/.claude/ratelimit-log.jsonl exists and gets new lines.
• In the sidebar, the line under the three rings ends with "derived from the official percentage in your status line feed". The week ring's tooltip says the same for the weekly limit.
• Right after a reading, /usage in Claude Code and the plugin's rings show the same percentages.

How the plugin uses the readings

Every reading carries the moment the current 5-hour window resets, so the plugin knows the real window start. The latest reading in the open window is the base of the 5-hour ring; between readings your new tokens are added at the rate your recent windows actually had. The latest reading of the current week from 10% upwards sets the weekly limit; readings below 10% are too coarse, because the figures come as whole numbers. When no reading fits, the plugin falls back to its own estimates, as before.

Known limits

Between two readings the plugin counts input and output only. Officially, cache writes also count toward the 5-hour window, so a cache rebuild (a new chat, or the first message after a long pause in a long session) shows up with the next reading. Readings only exist while a status line is shown or at the scheduled times.

Troubleshooting

What you see	What to do
The status line is empty	Node.js not found. Check node --version; on Windows put the full path to node.exe into the command
5h ? | week ?	No percentages delivered. Log in with your subscription instead of an API key, update Claude Code
Poll: "Claude Code CLI not found"	Set CLAUDE_BIN to the full path of claude
Poll: "No rate_limit_event in the output"	Run claude once by hand and log in with your subscription
The plugin still shows the old texts	No reading yet in the current window or week. Run the poll once by hand, then refresh the sidebar

Privacy and removal

Everything stays on your machine. Each line holds a timestamp, the two percentages with their reset times and, from the status line, the session and model ID. The plugin only reads the file and never runs the scripts itself. To remove it, delete the statusLine entry, the scheduled task (Unregister-ScheduledTask -TaskName 'TokenUsageLimitPoll') or the cron line, and if you like the log file. The plugin then falls back to its own estimates.

Updated 10 October 2026: the first version of this section did not mention Node.js and offered only the status line, which does not run in clients like Obsidian. Both are added.

Weekly Reset

The weekly limit resets at a fixed weekday and hour that differs per account. Everything week-shaped depends on it: the week ring, the forecast, the activity heatmap and the weekly estimate itself.

You normally do not have to set this. When you hit a weekly limit, Claude writes the next reset time into the message, and the plugin reads it from there — Settings then shows a green check and the date of the hit it was taken from. Until that has happened at least once, it assumes Sunday 18:00 and says so.

You can set it by hand under Settings → Weekly reset. A manual setting wins: automatic detection will not overwrite it, it only confirms it. Worth re-checking after a daylight-saving change if your reset appears to have moved by an hour.

The Sidebar, Heatmap & Calendar

An icon rail on the left switches between four pages. Since 2.0 this is the only layout — the former "Classic" view and the setting that switched between them have been removed.

Page	What is on it
Today	Three rings (5h window, today, this week), the activity heatmap for the current billing week, your last action, and the token breakdown
Calendar	The last two months as month grids
Analytics	The 7-day and N-day summaries as KPI tiles with trend sparklines, plus the model distribution
Settings	The same settings as the Obsidian settings tab, without leaving the sidebar

Everything on Today is from today or the current week by design; anything covering a longer span lives on Analytics or in the dashboard. In the header, Dashboard and Report generate files, CSV exports into your vault, and the arrow forces an immediate refresh.

Each of Today's four token rows carries a compact verdict marker — a green dot when the value is close to your own recent average, an amber arrow when it is running noticeably higher. The comparison window follows your Claude data retention setting, not a fixed number of days.

Activity heatmap

The grid on the Today page covers your current billing week. One row per calendar day, one cell per two hours, twelve cells a day.

It spans eight rows, not seven: a week running from, say, Sunday 18:00 to Sunday 17:59 touches eight calendar dates, so the first and last rows are deliberately partial. Cells outside the window are drawn as empty outlines — that is what makes the boundary of your cycle visible rather than hiding it inside artificial 24-hour slices.

Colour is pace, not volume. A 5-hour window holds two and a half 2-hour slots, so spending the whole window budget evenly means 40% of it per slot — the pace at which you arrive exactly at the wall as the window closes. Red marks that pace or faster; the bands below it are a quarter, a half, and up to it. Shading within a band shows where inside it a cell sits.

Three kinds of nothing are kept apart: outside the window (outline only), not yet reached (faint), and genuinely no activity (filled). Only the last one says anything about how your week went. Beside the grid, Active days counts the days of this billing week with any activity.

Activity calendar

The Calendar page shows the last two months side by side. Two rather than one, because at the start of a month a single grid would show only a handful of usable days and hide exactly the run-up you are looking for. The arrows move the pair further back, as far as the archive reaches; the calendar never goes into the future.

Each past day carries a coloured dot sized against your own recent daily average: green below average, amber around it, red for a spike (2x or more). Days with no activity have no dot. Click any day to add a private note — it is stored in the plugin settings, never in your session data.

Exporting Your Data (CSV)

Three CSV files: the project overview, the day-by-vault matrix, and the key figures. Two ways to get them, and they land in different places.

CSV button in the sidebar header — the plugin writes the files into your vault, into the folder set under Settings → CSV export folder. The menu names that folder before you click, so you know where they go. The same exports are in the Command Palette under "Export".

CSV Export menu in the dashboard — the dashboard is a browser page, so it hands the file to your browser and the browser decides where it goes, usually your Downloads folder. A web page cannot choose a target folder; that is a browser rule, not a missing feature.

Both routes produce raw numbers and ISO dates, ready to calculate with in Excel, Sheets or a script. Everything is generated locally — no upload, no network, same as the rest of the plugin.

Archive & Long-term Data

Why this exists at all. Claude Code manages its own local session files and deletes them on a schedule — 30 days by default, controlled by cleanupPeriodDays in its own ~/.claude/settings.json. Without a copy kept elsewhere, anything older than that window is simply gone.

What gets written, and where. Every time Obsidian is open (on refresh, roughly every 30 seconds, or immediately via the file watcher), the plugin checks which recent days already have an archive file and writes one for any day that is missing — including today's, updated in place as the day continues. Files land in a plain folder inside your vault, one per calendar day: Token Usage Archive/YYYY-MM-DD.md (folder name configurable in Settings). Each file holds aggregated totals only — token counts by type, session count, per-model token volume, and the vault/project breakdown for that day — never a prompt, a response, or anything resembling conversation content.

Once written, a past day's file is treated as final and left alone on later refreshes. The one deliberate exception: when a release adds an entirely new data source (agent-mode desktop sessions arrived this way in v1.8.0), a one-time rebuild silently rewrites the affected recent days once, so totals that were incomplete before that source existed don't quietly look wrong forever.

Archiving can be turned off entirely (Settings → Enable daily archive) if you would rather the plugin never create files in your vault — everything still works, but historical reach is then limited to whatever Claude Code itself still has on disk.

Dashboard & Vault/Project Reporting

The sidebar is built for a quick glance; the HTML dashboard (Command Palette → "Open Token Usage dashboard") is built for sitting down with the numbers. It regenerates a static HTML file and opens it in your browser — a snapshot, not a live connection, honestly timestamped as such in the corner.

Three tabs. Dashboard: five KPI cards (Weekly Forecast, Limit Health — only shown once a weekly limit estimate exists from an observed rate-limit hit, Cache Efficiency, Daily Velocity, Focus Score), a week status bar with an on-track forecast, then the daily chart, model distribution, histogram, Top Sessions, and any rate-limit events. Reports: the same figures laid out like the Markdown report. Projects: the vault/project breakdown, below.

The period dropdown (30/60/180/360 days) reshapes the summary cards, daily chart, and cache chart instantly, client-side — a full 360-day window is always embedded. Model distribution, the histogram, Top Sessions, and rate-limit detection stay on the live data window regardless, since the archive that powers longer periods only holds daily aggregates, not that level of session detail. This matters most for rate-limit estimates specifically: they are derived from how many tokens were counted the moment a limit was actually hit in the live window.

Projects tab — for more than one vault or client. Each row is a folder a Claude Code session started in: your Obsidian vault, the desktop app's Agent Mode bucket (shown as Claude Desktop (Agent Mode)), or any other directory you ran Claude Code in directly. Folders under 1% of the total collapse into a single "Other" row. Tick "Show sub-project detail" to expand any vault whose working directory drifted during a session into its own per-subfolder split, right inline in the table — the same breakdown is also in the standalone Vault_Token_Usage_Projects.md export, handy for splitting costs across clients when billing. Columns are sortable by clicking their header.

Export commands (Command Palette), each overwriting its target file in your vault on every run: 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). All three paths are configurable, see Settings Reference.

What is Measured (and What Is Not)

The plugin covers every way you run Claude Code: terminal, Obsidian, an editor such as VS Code, and desktop Agent Mode — all flowing into the same numbers (see Data Sources & Transparency for exactly how). What it cannot show is ordinary chat — conversations in the Claude desktop app's normal chat window, or on claude.ai in a browser. Those never write token counts to disk in the format this plugin reads; the only signal available there is a rounded percentage of your plan limit. If a day's actual usage feels higher than the dashboard shows, this is very often why.

Settings Reference

Every setting the plugin has, in the order it appears in Settings → Token Usage. Defaults are chosen so a fresh install works well untouched.

Setting	Default	What it does
Language	English	Display language for the plugin UI (English, German, French, Italian). Takes effect immediately.
Weekly reset	auto-detected	Weekday and hour your weekly limit resets. Read automatically from your own weekly-limit messages; a manual setting always wins. See Weekly Reset.
Report period	30 days	How far back the dashboard and report look. Beyond your Claude data retention window, older days are filled in from the archive automatically.
Enable daily archive	On	Writes one small Markdown summary file per day into your vault. Turn off if you don't want the plugin creating files in your vault.
Claude data retention	30 days (Claude Code's own default)	How long Claude Code itself keeps session files, read from and — if changed here — written back to Claude Code's own settings.
Auto-refresh interval	30 seconds	Fallback polling interval; the file watcher already triggers immediately on every new Claude response.
Report path in vault	Token Usage Report.md	Vault-relative path for the Markdown report.
Vault report path in vault	Vault_Token_Usage_Projects.md	Vault-relative path for the standalone per-vault/per-project export.
Dashboard path in vault	Token Usage Dashboard.html	Vault-relative path for the HTML dashboard.
Archive folder in vault	Token Usage Archive	Vault-relative folder holding the daily archive files.
CSV export folder in vault	Token Usage Exports	Vault-relative folder the plugin writes CSV exports into. See Exporting Your Data.
Archive folder in vault	Token Usage Archive	Vault-relative folder holding the daily archive files.

Every path/folder field has a "Show in folder" button next to it that opens the exact location in your system file manager.

API Pricing Reference

Anthropic's API prices per million tokens — standard input / output, as of October 2026:

Model	Input / 1M	Output / 1M
Haiku 5.5 *	$0.10	$0.50
Haiku 4.5	$1.00	$5.00
Sonnet 5.5	$2.00	$10.00
Sonnet 5 **	$2.00	$10.00
Sonnet 4.6	$3.00	$15.00
Opus 5.5	$4.00	$20.00
Opus 5	$5.00	$25.00
Fable 5.1	$10.00	$50.00
Fable 5	$10.00	$50.00

* Haiku 5.5 for prompts up to 100,000 tokens; above that $0.50 input / $2.50 output.
** Sonnet 5 launched with $2 / $10 as introductory pricing until 31 August 2026. Anthropic has since made it the standard price; the announced increase to $3 / $15 did not happen. Our earlier version of this page still said it would.

Cache pricing on top of standard input rates:

• C.Write: 1.25× the model's standard input price for a 5-minute cache, 2× for a 1-hour cache (the usual kind for Claude Code on a subscription)
• C.Read: 0.1× the model's standard input price; 0.05× on Opus 5.5 and Sonnet 5.5, 0.025× on Fable 5.1

Why Costs Accumulate

A single request is rarely expensive. Quick calculation with Sonnet 5 at its standard price of $2 / $10 per million:

• 10,000 input tokens × $2 / 1M = $0.02
• 2,000 output tokens × $10 / 1M = $0.02
• Total: roughly $0.04

That is almost nothing. The issue is repetition and context growth. Each new message in a session typically re-sends the conversation history and any open files as input. After ten exchanges, message ten carries all nine previous turns plus any attached documents — so the total input count grows with every step, even when you only type a short question.

The question itself is rarely the cost driver. What gets sent along with it is.

What Drives Costs Up

• Long sessions where a large context window is re-sent with every request
• Attaching large files or entire codebases that travel as input with each message
• Frequent rapid requests in a short time span
• Using a high-tier model for tasks a cheaper one handles equally well

Practical Tips

Measure first. The plugin's daily chart and session table show where tokens actually go. You cannot optimize what you have not looked at.

Avoid unnecessary context. Large files attached "just in case" add to every input count. Attach only what Claude needs for the current task.

Choose the model by task. Not every request needs Opus. Quick questions, formatting tasks, and simple code edits often work well with Haiku or Sonnet at a fraction of the cost. Compare quality and total cost per completed task, not just price per token.

Understand the cache. A spike in C.Write at the start of a session is normal — a large context was established. What matters is whether C.Read follows. If the same context is reused across many requests, the upfront write cost amortizes quickly and your effective cost per request drops significantly.

Use the dashboard. The HTML dashboard (opened via the chart button in the sidebar) shows your usage history — 30, 60, 180, or 360 days via the period selector in the header — plus model distribution and the cache efficiency trend. Looking at data over days reveals patterns a single session view cannot.

FAQ & Troubleshooting

Does this work on macOS and Linux, or only Windows? All platforms — the core plugin has always been platform-neutral. The only platform-specific detail is Claude Desktop's Agent Mode session location, which is a Windows-only quirk; see Data Sources & Transparency for the full explanation.

"This Session" shows more tokens than "Today" — is that a bug? No. A Claude Code session can run across a midnight boundary; see the three time views above.

Why don't I see a "Limit Health" card on the dashboard? Anthropic does not publish a fixed weekly token limit — this plugin only shows an estimate once it has actually observed a rate-limit hit in your own data, or, since 2.1.0, once the optional status line feed has delivered an official percentage. Until then, the card stays hidden rather than guess.

My browser chat (claude.ai) or the desktop app's normal chat usage doesn't show up anywhere. Expected, not a bug — see What is Measured and Data Sources & Transparency above.

Obsidian's plugin review flagged "Direct Filesystem Access" — should I be worried? No, that warning is expected and unavoidable for what this plugin does — see Data Sources & Transparency for exactly what is and isn't read.

A day's numbers changed after I updated the plugin — did old data get corrupted? Almost certainly not — see the one-time rebuild mechanic under Archive & Long-term Data.

Can I track more than one Obsidian vault, or split usage by client? Yes — see Dashboard & Vault/Project Reporting.

Do I need an API key or an Anthropic account to use this plugin? No. It reads local files Claude Code already writes on your own machine.

I closed Obsidian for a few weeks — is that usage gone for good? If it fell outside your configured Claude data retention window while Obsidian was closed, yes — see the honest-limit box under Archive & Long-term Data.

Compatibility & Claude Code Updates

Token Usage reads the JSONL session files that Claude Code writes locally. Anthropic updates Claude Code regularly — sometimes in ways that affect how session data is recorded or how internal telemetry is counted.

We review Anthropic's release notes with each major Claude Code release and update the plugin where necessary. Significant compatibility changes are documented in the plugin changelog on GitHub.

About This Plugin

Token Usage is an open-source Obsidian community plugin. It reads local JSONL files written by Claude Code — no data is sent anywhere. Something not covered above? Issues and feature requests are welcome any time.

• GitHub: beolatn/TokenUsage
• Obsidian Plugin Directory: Token Usage
• Author: Björn-Olaf Lange · langeatn.de

Prices cited on this page are sourced from Anthropic Platform Docs. Last updated October 2026. Prices may change — always check the current rates on the Anthropic website.