Token Usage is an Obsidian plugin that tracks Claude Code token consumption from locally stored session files.
Instead of relying on API access or external dashboards, Token Usage reads Claude Code's local JSONL files and displays real-time token statistics directly inside Obsidian — broken down by type, time range, and model.
- Live sidebar panel with token breakdown across five time ranges
- Separate display of all four token types: Input, Output, Cache Write (C.Write), Cache Read (C.Read)
- Rolling 5-hour session window matching Claude Code's internal rate-limit window
- 7-day bar chart with model distribution — stacked by Haiku, Sonnet, Opus, Fable
- HTML dashboard with 30-day charts, model donut, top sessions table, and cache efficiency analysis
- Markdown report export directly into your vault
- Built-in Help panel with full glossary and cost reference
- Command Palette integration for all major actions
- No API key required — reads local files only
- Local-first and privacy-friendly
As Claude Code usage grows, understanding where tokens actually go becomes important for both cost awareness and workflow optimization.
Most existing solutions require organization-level API access or live in separate dashboards outside your daily workflow.
Claude Code already stores detailed usage information locally in JSONL session files. Those files contain all token data, timestamps, session identifiers, and model information.
Token Usage brings those insights directly into Obsidian, where many users already manage their projects, notes, and knowledge base.
Token Usage scans Claude Code session files stored at ~/.claude/projects/ and extracts token data from every recorded interaction.
Example JSONL entry:
{
"input_tokens": 3,
"cache_creation_input_tokens": 16926,
"cache_read_input_tokens": 0,
"output_tokens": 252
}The plugin aggregates all four token fields across sessions and time ranges. All calculations run locally on your device.
A live file watcher detects new activity the moment Claude Code writes a response. A configurable fallback polling interval runs in parallel.
Real-time Claude Code token usage in the Obsidian sidebar.
A rolling window covering the past 5 hours — matching Claude Code's own rate-limit period. Shows Input, Output, C.Write, and C.Read as separate rows.
Four time-range sections, each showing the same four token rows with a small intensity bar for quick visual comparison.
A stacked percentage bar showing the model distribution across the past 7 days, colored by model family:
| Model | Color |
|---|---|
| Haiku | Cyan |
| Sonnet | Blue |
| Opus | Purple |
| Fable | Amber |
| Other | Gray |
Cache Write (C.Write) and Cache Read (C.Read) are shown as separate rows throughout the sidebar because they have very different cost implications:
- C.Write (purple) — approximately 1.25× standard input price. A one-time cost to establish the cache.
- C.Read (amber) — approximately 0.10× standard input price. Ten times cheaper than regular input.
The ratio C.Read ÷ C.Write is the Reuse Factor. A high value means the same context is being reused efficiently across many requests.
The dashboard button in the sidebar header generates a self-contained HTML report and opens it in your default browser.
The dashboard includes:
- Summary cards — total tokens, requests, active days, and average tokens per request over 30 days
- Daily stacked bar chart — 30 days of input, output, and cache tokens by day
- Model distribution donut — share of each model family over 30 days
- Request size histogram — distribution of tokens per individual request
- Top sessions table — the 10 most token-intensive sessions by date and identifier
- Cache efficiency section — 30-day line chart with C.Write and C.Read, Reuse Factor card, and a dynamic interpretation of your usage pattern
The dashboard uses Chart.js (loaded once from CDN) and works offline after the first load.
The "?" button in the sidebar header toggles between the data view and a built-in glossary. The glossary explains:
- What a token is
- The difference between Input and Output
- What C.Write and C.Read mean and why they matter
- How to read the Reuse Factor
- What the 5-hour session window represents
- How the model colors map to model families
- How sessions are counted
- Approximate API cost reference per model
A link at the bottom of the glossary opens the full help page at langeatn.de/docs/token-usage/ in your browser. The page is available in English and German.
The "Create Token Usage report" command (also available via the document icon in the sidebar header) writes a Markdown report file to your vault. The report covers:
- Last action with all four token types
- Current session and today
- 7-day and 30-day summaries
- Cache efficiency ratio over 30 days
The report path is configurable in Settings.
- Open Obsidian Settings → Community Plugins
- Search for Token Usage
- Install and enable
- Download the latest release assets:
main.js,manifest.json,styles.css - Create the folder
<vault>/.obsidian/plugins/token-usage/ - Copy the three files into that folder
- Restart Obsidian
- Enable Token Usage under Settings → Community Plugins
After enabling the plugin:
- Click the activity icon in the left sidebar to open the Token Usage panel.
- Use Claude Code normally — the panel updates automatically whenever a new response is recorded.
- Click the chart icon in the panel header to open the HTML dashboard.
- Click ? to toggle the built-in glossary.
No additional setup, API keys, or cloud services required.
| Command | Action |
|---|---|
| Open Token Usage | Opens the sidebar panel |
| Create Token Usage report | Writes a Markdown report to your vault |
| Open Token Usage dashboard | Generates and opens the HTML dashboard |
| Setting | Default | Description |
|---|---|---|
| Auto-Refresh (seconds) | 30 | Fallback polling interval in addition to the live file watcher |
| Report path | Token Usage Report.md | Vault-relative path for the generated Markdown report |
| Dashboard path | Token Usage Dashboard.html | Vault-relative path for the generated HTML dashboard |
Token Usage is built with a local-first philosophy.
- No data is sent to external services
- No telemetry
- No API keys required
- No cloud processing
- All calculations are performed locally on your device
Your Claude Code usage data stays on your machine.
Version number in the sidebar footer shows an outdated version after an update.
This is not a code bug. Obsidian caches the loaded plugin manifest in memory. Toggling the plugin off and on may not fully reinitialize the manifest object. Fix: perform a full Obsidian restart after updating the plugin files. The correct version will display after restart.
Contributions, bug reports, feature requests, and suggestions are welcome.
- Fork the repository
- Create a feature branch
- Commit your changes
- Open a pull request
If you encounter a problem or have an idea for improvement, please open an issue in the GitHub repository.
Full documentation and glossary: langeatn.de/docs/token-usage/
MIT License — see the LICENSE file for details.
- Obsidian
- Anthropic Claude Code
- The Obsidian Plugin Community
Built to answer a simple question:
"Where did all my tokens actually go?"