Docs · Token Usage Plugin
Understanding Token Usage
in Claude Code
Token Usage is an Obsidian community plugin that reads your Claude Code session logs and shows live token consumption directly in your sidebar. No API key required, no data leaves your machine — it reads the JSONL log files that Claude Code writes locally to ~/.claude/projects/.
This page explains every term you see in the sidebar, the dashboard, and the reports — and what the numbers actually mean for your costs.
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.
Every API call is billed on two counts: how many tokens go in, and how many tokens come out. That is all that matters for the bill.
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.
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
The relationship between these two numbers tells a story about how you are working.
Reuse Factor = C.Read ÷ C.Write
| Reuse Factor | What it signals |
|---|---|
| Below 2× | High context churn — lots of new material, little reuse. Exploratory mode. |
| 2× to 8× | Balanced. Cache is paying off, but context shifts regularly. |
| Above 8× | Deep focus mode — same files, long session, cache working hard for you. |
A high reuse factor is generally a good sign: you are working deeply on the same problem and the cache is saving you money. The dashboard shows this ratio in the Cache Efficiency section, including a 30-day line chart with C.Write in purple and C.Read in amber — matching the sidebar colors.
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.
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.
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)
These are API usage prices, not monthly subscription prices for the Claude app or Claude Code Max. The Token Usage plugin reads locally logged data — it makes no API calls and has no access to your Anthropic billing account.
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 30 days of history, model distribution, and the cache efficiency trend. Looking at data over days reveals patterns a single session view cannot.
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.
- 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.