The original article had the right instinct and the wrong center. A dramatic 700M-token spike is not a safe headline unless the source proves the number.
The durable story is local evidence. Claude Code writes JSONL transcripts under the user's machine. phuryn/claude-usage reads those transcripts, normalizes turns into SQLite, dedupes streaming records, and renders the result as a browser dashboard or VS Code sidebar.
That matters for teams using Claude Code heavily. A cap warning, a sudden cost estimate, or a noisy session feels mysterious until the team can ask which project, which model, which cache bucket, and which assistant turn created the load. claude-usage is useful when it answers those questions without sending data to a vendor API.
The article to write is not about a spike
A spike can be the incident that makes someone install the dashboard, but it should not be the claim unless the source material includes the numbers and method. This repository does not need that hook.
The better reader promise is narrower and stronger: use local Claude Code logs as evidence. If the chart shows a large day, verify it from the scanner's model, session, project, cache, and message-id behavior before changing team policy.
Where it sits next to CodeBurn
This should not duplicate the CodeBurn article. CodeBurn is a broad cost ledger across several coding agents and providers. claude-usage is Claude Code specific and closer to an audit viewer for one local log format.
That narrower scope is a strength. The tool knows about ~/.claude/projects/, the Xcode ClaudeAgentConfig directory, Claude Code assistant records, cache-read and cache-creation fields, model names, message IDs, project paths, and the VS Code extension path. It is not trying to normalize the whole agent market.
Install it as an evidence tool
The low-friction path is Homebrew:
brew install --formula https://raw.githubusercontent.com/phuryn/claude-usage/main/Formula/claude-usage.rb
claude-usage dashboardThe source path is just as direct:
git clone https://github.com/phuryn/claude-usage
cd claude-usage
python3 cli.py dashboardNo pip install and no virtual environment are required. The Python tool uses the standard library: sqlite3, http.server, json, and pathlib.
Run the terminal checks before the chart
Do not start with a screenshot. Start with the data path:
python3 cli.py scan
python3 cli.py today
python3 cli.py week
python3 cli.py statsThose commands force the first question: is there a database, and did the scanner read the transcript files? The database lives at ~/.claude/usage.db. The default scan walks ~/.claude/projects/ and, on macOS, the Xcode coding-assistant project directory. For a controlled review, point the scanner at a copied transcript folder:
python3 cli.py scan --projects-dir /tmp/claude-transcripts-reviewUnderstand the scanner before trusting the total
The scanner is the reason this tool is more than a chart. It creates three tables: sessions, turns, and processed_files.
turns is the evidence table. Each row represents an assistant response with input tokens, output tokens, cache-read tokens, cache-creation tokens, model, timestamp, cwd, tool name, and message ID.
sessions is the summary table. It stores denormalized totals, project name, timestamps, branch, primary model, and turn count.
processed_files is the incremental-scan ledger. It records path, modification time, and line count so later scans can skip unchanged files or read only new lines.
The message-id rule prevents fake spikes
The most important implementation detail is streaming dedupe. Claude Code can write several JSONL records for one API response. Those records share message.id, and only the last record has the final usage tally.
scanner.py stores the latest record for each non-empty message ID in a dictionary. The database also has a conditional unique index on turns.message_id. After insert, scan() recomputes session totals from turns so ignored duplicate rows cannot leave aggregate totals too high.
That design is exactly what a token-spike investigation needs. Before blaming the agent, verify that the scanner is counting final assistant responses, not every streaming partial.
Cost is per turn, not per session
AGENTS.md in the repo calls out another invariant: costs are computed per turn because each turn has its own model. A session can move across Opus, Sonnet, Haiku, and unknown model strings. Summing all tokens first and applying one model price is wrong.
The CLI and dashboard both keep model-aware cost logic. Unknown and non-Anthropic model names return no price instead of being charged as Sonnet. That conservative behavior is useful when local logs include experiments or future model strings the tool does not know yet.
Treat dollars as estimates
The dashboard uses API pricing to estimate dollars, and the README says subscription users should not read those estimates as their actual plan cost. That caveat should stay near every cost chart.
For Pro or Max users, the operational question is usually cap pressure, not invoice math. API-rate dollars still help compare sessions because they weight input, output, cache creation, and cache read differently. They do not say what the subscription charged.
The practical policy is: use tokens and sessions as evidence; use estimated dollars as a relative signal; verify current prices against Claude's pricing page before publishing numbers.
Use the dashboard for triage
The browser dashboard runs on localhost, defaults to port 8080, refreshes every 30 seconds, and exposes model filters plus date ranges. It shows daily token usage, hourly distribution, model totals, top projects, session tables, cache read, cache creation, and estimated cost.
A useful triage pass looks like this:
1. Pick the suspect range: today, week, month, or a custom review window.
2. Filter to the model family that triggered cap pressure.
3. Sort recent sessions by input plus output tokens.
4. Check project and branch fields before blaming a workflow.
5. Compare cache creation against cache read; high creation can mean large prompts are being written repeatedly.
6. Export CSV for any incident note or team review.The VS Code extension changes adoption
The VS Code extension is not a decorative wrapper. It removes the separate browser step for people already working inside the editor. The extension bundles the Python sources, starts the dashboard server, picks a local port when configured port is 0, and embeds the dashboard in an activity-bar webview.
The settings are practical: claudeUsage.pythonPath, claudeUsage.cliPath, and claudeUsage.port. The command surface is also small: open dashboard, rescan transcripts, restart server, and show logs.
For a team, that means there are two rollout modes. CLI-first for terminal-heavy users. Sidebar-first for VS Code users who want usage evidence beside the work.
Privacy boundaries are clear
The tool's value depends on locality. The README and extension docs say the data path stays on the machine: local JSONL transcripts to local SQLite to localhost dashboard. The VS Code extension says it makes no API calls and sends no telemetry.
That does not remove every risk. Local transcript files may contain prompts, file paths, project names, and snippets of work context. Do not expose the dashboard on 0.0.0.0 unless the machine and network are controlled. If a team exports CSV, treat it as work data, not harmless metrics.
Know what it cannot see
The README names an important blind spot: Cowork sessions are not captured because they run server-side and do not write local JSONL transcripts.
There are other practical boundaries. If Claude Code changes its JSONL schema, the scanner assumptions may need updates. If a transcript lacks model data, the dashboard groups it as unknown. If a team deletes old transcripts before scanning, the dashboard cannot reconstruct them.
So the article should frame claude-usage as local evidence, not total account truth.
A cap review runbook
When someone reports a cap problem, run a small, repeatable review:
python3 cli.py scan
python3 cli.py today
python3 cli.py week
python3 cli.py statsThen inspect the dashboard:
- Which project has the largest total?
- Which model family created the largest input and output buckets?
- Is cache creation high relative to cache read?
- Did one session dominate the day?
- Did the suspect session use tool-heavy prompts, repeated large context, or a branch with generated files?
- Are there unknown model rows that should be excluded from cost interpretation?If the answer points at one project, fix the workflow. If it points at repeated cache creation, change context strategy. If it points at mixed models, review model-routing choices.
What to add to AGENTS.md
A team that adopts claude-usage should make the evidence rule explicit:
For Claude Code cap or usage incidents, do not rely on screenshots alone. Run claude-usage scan, inspect ~/.claude/usage.db through the dashboard or CLI, and cite project, model, session, cache-read, and cache-creation evidence. Treat API-price dollars as estimates, not subscription billing. Do not publish spike numbers unless the transcript-derived method is included.That rule prevents a local dashboard from becoming another vague metric wall.
When not to use it
Skip claude-usage if the team needs cross-provider accounting, central reporting, or policy across Codex, Cursor, Cline, Aider, and Claude Code together. That is closer to the CodeBurn lane.
Use claude-usage when the disputed question is Claude Code specific: which local sessions used the tokens, which project or branch drove the load, whether cache behavior changed, and whether the dashboard total survives message-id dedupe.
The boundary is healthy. A small local tool should answer the local question well.
Save the phuryn/claude-usage article as a local evidence guide, not a spike story. It is useful for Claude Code teams that need transcript-backed cap triage, scanner trust rules, per-turn model costing, cache visibility, and a VS Code adoption path.
Practical takeaway
Install claude-usage, run scan, check today, week, and stats, then use the dashboard to trace project, model, session, cache-read, and cache-creation buckets. Treat API dollars as estimates, avoid unproven spike claims, and use the VS Code extension when the team wants the same evidence inside the editor.