claude-usage

The user invoked /claude-usage (or asked a natural-language question about Claude Code token usage). Argument: $ARGUMENTS

Run ccusage (parses ~/.claude/projects/**/*.jsonl) to produce a token + cost overview. Pick the subcommand based on the argument.

Argument	Command to run	Purpose
(empty) or daily	npx ccusage@latest	Daily token + cost rollup (default)
session	npx ccusage@latest session	Per-session breakdown
current	(resolve current session UUID, then) npx ccusage@latest session -i <uuid>	Just this session — see workflow below
monthly	npx ccusage@latest monthly	Monthly rollup
project	npx ccusage@latest session --json | python "${CLAUDE_PLUGIN_ROOT}/scripts/usage-by-project.py"	Per-project cost breakdown
live or --live	do not run — print instructions	Live 5h-block burn rate (blocking TUI)
--g	npx ccusage@latest session --json | python "${CLAUDE_PLUGIN_ROOT}/scripts/usage-terminal.py"	Terminal bar charts (daily cost + top projects)
--graph	python "${CLAUDE_PLUGIN_ROOT}/scripts/usage-app.py"	Launch Streamlit dashboard (blocking)
--report	npx ccusage@latest session --json | python "${CLAUDE_PLUGIN_ROOT}/scripts/usage-report.py" --outdir "$HOME/.claude/claude-spend-reports"	Write CSV + Markdown report for finance/admin

The Python-backed subcommands (project, --g, --graph, --report) need extra packages: pandas, plotext (for --g), plotly + streamlit (for --graph). If you see ModuleNotFoundError, tell the user to run pip install pandas plotext plotly streamlit and retry.

If python is not on PATH (common on Windows), retry with py instead.

Workflow for daily / session / monthly

1. Run the command via Bash. The output is usually 30–60 KB — let the Bash tool persist it to disk if needed and read back the tail. The totals row + the last ~10–15 rows of detail are what matter.
2. Produce a tight digest in this order:
   • All-time totals — total tokens, cost equivalent, span of dates covered.
   • Recent activity table — Markdown table of the last 10–15 days (or top 10 sessions / last 6 months for the other modes). Columns: Date / Session / Month · Tokens · Cost-eq · Models used.
   • 2–4 bullet observations — spikes, model-mix shifts, cache-read ratio (cache reads / total — should be >80% if prompt caching is working), anything notable.
3. End with a "Useful follow-up" section listing the other /claude-usage subcommands so the user can drill in.

Workflow for current

Shows just this Claude Code session — not all sessions.

1. Resolve the current session UUID via PowerShell. The encoded folder name under ~/.claude/projects/ is the cwd with :, \, / all replaced by -. The current session is the most-recently-modified *.jsonl in that folder:

   $encoded = (Get-Location).Path -replace '[:\\/]', '-'
   $uuid = (Get-ChildItem "$env:USERPROFILE\.claude\projects\$encoded\*.jsonl" |
            Sort-Object LastWriteTime -Descending | Select-Object -First 1).BaseName
   Write-Output $uuid
   

2. Run ccusage filtered to that ID: npx ccusage@latest session -i <uuid> (substitute the resolved UUID).
3. Produce a tight digest — since this is one session, keep it to:
   • Total cost for the session
   • Total tokens (input / output / cache-read / cache-write)
   • Cache-read ratio (>80% = good prompt-cache discipline)
   • Model(s) used
4. Mention the caveat once at the bottom: "Resolved by most-recently-modified JSONL in this cwd. If another Claude Code window in the same project has written more recently, that session is shown instead — open this in a fresh window if unsure."
5. End with a "Useful follow-up" suggesting session (all sessions in this project) or the per-session statusline ($X ⏱Ym Zs) which already shows the live cost for this window with no command needed.

Workflow for project

1. Run npx ccusage@latest session --json | python "${CLAUDE_PLUGIN_ROOT}/scripts/usage-by-project.py" via Bash. The aggregator script:
   • Pulls every session row from ccusage
   • Joins each session's UUID to its project folder under ~/.claude/projects/<encoded-path>/ (including subagent sessions under <parent-uuid>/subagents/)
   • Aggregates cost, tokens, sessions, and models per project
   • Emits a ready-to-display Markdown table sorted by total cost descending
2. Forward the script output to the user verbatim as the primary report. The output already includes:
   • All-time totals row (cost, sessions, projects, cache-read ratio)
   • The per-project Markdown table
   • A note about unmapped sessions if any exist
3. Then add 2–3 bullet observations below the table — biggest spenders, cache-hit ratio health (>80% is good prompt-cache discipline), unexpected concentrations.
4. End with a "Useful follow-up" section suggesting session or monthly for drilling further into the top project.

Notes:

• Non-Claude sessions (codex, gemini, etc.) get bucketed under (non-claude: <agent>).
• Sessions whose JSONL no longer exists under ~/.claude/projects/ get bucketed under (unmapped-claude-sessions).

Important framing note to include once at the top of the digest:

"Cost" is the API-equivalent. If you're on a Claude Pro/Max plan, this represents the value extracted, not money out of pocket.

Workflow for live or --live

ccusage blocks --live is a full-screen TUI that streams indefinitely — do not call it from Bash (it will hang or get killed by the timeout, and the captured output is meaningless).

Instead:

1. Print the exact command for the user to run in their own terminal:

   npx ccusage@latest blocks --live
   

2. Briefly explain what they'll see (current 5-hour usage block, burn rate, projected cost-to-quota if on Claude Max). One short paragraph is enough.
3. Do not print any other output — no daily/session digest, no historical totals. --live means "only the live view".

Workflow for --g

1. Run the piped command via Bash. The script prints directly to the terminal — no browser needed.
2. Forward the output verbatim. It contains:
   • A summary line: total cost, sessions, cache ratio, date span
   • A vertical bar chart of daily cost (last 30 days)
   • A horizontal bar chart of top 10 projects by cost
3. No further commentary needed — the charts are self-explanatory. You may add one sentence if anything notable jumps out (e.g. a spike day).

Workflow for --graph

1. scripts/usage-app.py shells streamlit run which blocks the foreground. Run it with run_in_background=true via Bash.
2. Tell the user: "Dashboard starting at http://localhost:8501 — three tabs (Overview, By project, By tool). Click 'Refresh data' to reload. Kill the background task to stop."
3. Do not try to scrape the dashboard output.

Workflow for --report

1. Run the piped command via Bash. The script writes two files to ~/.claude/claude-spend-reports/:
   • claude-usage-YYYYMMDD-HHMM.csv — one row per (day × project), columns: date, project, cost_usd, tokens, cache_read_tokens, cache_read_pct
   • claude-usage-YYYYMMDD-HHMM.md — totals + top-10 projects + top-10 tools tables, ready for paste into a finance ticket
2. Print the two filenames so the user can grab them.
3. Add a one-line summary: "Total $X across N days, top spender: Y."

Notes

• ccusage is offline — it reads the local session logs, no auth needed, no network call beyond npm install of the package itself.
• First invocation downloads the npm package (~one-time ~5–10 s warmup); subsequent calls are fast.
• The Bash default 2-minute timeout is plenty for daily / session / monthly — don't extend it.
• If the user's argument isn't one of the recognised values, default to daily and mention what you did in one line so the user can correct.
• --graph blocks indefinitely — always use run_in_background=true.
• This skill complements /claude-spend: /claude-spend is what Anthropic bills you (authoritative), /claude-usage is what your local logs estimate (great for per-project attribution).