Understanding Token Usage
in Claude Code

Contents

• Getting Started
• Data Sources & Transparency
• Core Concepts (tokens, caching, the Reuse Factor, Focus Score, models, sessions)
• NextGen Sidebar & Activity Calendar
• 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 default view (Classic sidebar) works immediately. The newer icon-rail layout with heatmap, KPI tiles, and calendar is one toggle away: Settings → Sidebar appearance → NextGen — see below. Switching back is fully reversible and never affects the underlying data.

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

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.

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.

Cache writes cost approximately 1.25× the standard input price — slightly more expensive than regular input. It is a one-time investment: you pay a little more upfront so that subsequent requests can skip reprocessing the same content.

The plugin displays C.Write in purple throughout the sidebar to signal the higher cost.

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 about 10% of the standard input price — ten times cheaper than regular input. 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 amber 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 purple and C.Read in amber — 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.

Last 5 Hour Session

Claude Code operates on a rolling 5-hour window for its internal rate limits. The plugin tracks the same window: it sums all activity from the past 5 hours and shows Input, Output, C.Write, and C.Read as separate rows.

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

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: Last 5 Hour Session, 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
Last 5 Hour Session	Rolling window: everything from 5 hours ago until now	Continuously — oldest entry drops off as time passes
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" if your current time is before 05:00 — the rolling window then reaches back into yesterday. From 05:00 onwards, the 5-hour window is always fully contained within today.

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.

NextGen Sidebar & Activity Calendar

The sidebar has two layouts, switchable anytime in Settings → Sidebar appearance. Classic is the original single-page view and stays the default. NextGen switches to an icon rail with dedicated Today, Overview, and Settings pages, replaces the daily bar chart with a 7-day activity heatmap (six time-of-day blocks per day), and shows the 7-day and N-day summaries — N follows your Report period setting — as colored KPI tiles with trend sparklines.

In NextGen, each of Today's four token rows also gets 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 whatever Claude data retention period you have configured, not a fixed number of days.

Switching between Classic and NextGen is fully reversible and does not affect any of the underlying data or the dashboard.

Activity calendar. Since v1.8, NextGen also pins a month calendar to the bottom of every page. Each past day gets a colored dot scaled to your own recent daily average — green below it, amber around it, red for a spike of 2× or more; days with no activity stay blank. Navigate back as far as your archive reaches; it never runs into the future and is display-only. Switch it off under Settings → Activity calendar if you prefer a shorter sidebar.

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.
Sidebar appearance	Classic	Classic keeps the original single-page sidebar as-is. NextGen switches to the icon rail described above. Fully reversible.
Activity calendar (NextGen)	On	Shows the month calendar at the bottom of every NextGen rail page. No effect on Classic.
Auto-refresh interval	30 seconds	Fallback polling interval; the file watcher already triggers immediately on every new Claude response.
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 at all.
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 to ~/.claude/settings.json, with an automatic .bak backup first.
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.

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 August 2026:

Model	Input / 1M	Output / 1M
Haiku 4.5	$1.00	$5.00
Sonnet 5 *	$2.00	$10.00
Sonnet 4.6	$3.00	$15.00
Opus 5	$5.00	$25.00
Fable 5	$10.00	$50.00

* Sonnet 5 introductory pricing valid until 31 August 2026. After that: $3.00 input / $15.00 output.

Cache pricing on top of standard input rates:

• C.Write: approximately 1.25× the model's standard input price
• C.Read: approximately 0.10× the model's standard input price (10× cheaper)

Why Costs Accumulate

A single request is rarely expensive. Quick calculation with Sonnet 5 at introductory price:

• 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. 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 August 2026. Prices may change — always check the current rates on the Anthropic website.