mcpbeat

Claude Usage Analyst

daymade/claude-usage-analyst

Analyze Claude Code and Claude Desktop Code token usage, cost, quota burn, model mix, cache read/write, and 5-hour block consumption using ccusage evidence. Use when the user asks why Claude quota was exhausted, whether a model such as fable/opus/sonnet is unusually expensive, how many tokens were spent today or historically, or needs a human-friendly explanation of local Claude Code CLI/Desktop usage.

4k tokens
context cost
the whole folder, loaded on every use
5
files
ships runnable scripts
0
copies elsewhere
how many repositories repackaged it
1314
stars on the repo
on the repository, not the skill itself

Install

one command, takes just this skill from the repository 
npx skills add https://github.com/daymade/claude-code-skills --skill claude-usage-analyst

The instruction itself

5 sections, as written by the author

Claude Usage Analyst

Overview

Use this skill to produce evidence-based usage explanations from local ccusage data. Separate observed numbers from interpretation, and explain quota burn in human terms.

Workflow

  • Verify ccusage is available:
   ccusage --version

If missing, install or update with npm install -g ccusage@latest or run with npx ccusage@latest.

  • Run the bundled analyzer for the requested window:
   python3 /path/to/claude-usage-analyst/scripts/analyze_claude_usage.py \
     --since YYYY-MM-DD --until YYYY-MM-DD --timezone Asia/Shanghai

Default --since/--until is today in the selected timezone.

For historical comparison, set --since to an earlier date such as the first day of the month; otherwise rank/median fields only describe the single target day.

  • If the user asks about a specific model comparison, pass aliases:
   python3 scripts/analyze_claude_usage.py --model-a fable --model-b opus-4-8
  • Read references/explanation-guide.md when writing the final answer.

Evidence Rules

  • Base numeric claims on ccusage output or the bundled analyzer output.
  • State the scope: ccusage claude measures local Claude Code usage logs, including Claude Desktop's Claude Code sessions when those local logs exist. It is not a complete ordinary Claude.ai chat bill.
  • Report dates with timezone.
  • Explain cache clearly: cache read tokens are still usage/quota pressure even though the user did not type those words.
  • Do not infer Anthropic plan quota rules from local token counts unless the user provides plan details. Say "quota-like pressure" or "ccusage estimated cost/token burn" when exact plan accounting is unknown.
  • When comparing models, compare both token volume and estimated cost. A model can have similar token volume but higher cost.

Output Shape

Use this structure unless the user asks otherwise:

  • Short conclusion in plain language.
  • Evidence table: total tokens, cost, input, output, cache create, cache read.
  • Model comparison table.
  • 5-hour block table when quota exhaustion is discussed.
  • Explanation of why the burn happened.
  • Confidence and caveats.

Keep the answer readable for non-technical users. Avoid unexplained terms like "cache read" without a one-sentence translation.

How to use it

Copy the folder

Take daymade/claude-usage-analyst from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.

Install what it needs

The instructions reference npm, npx. Without those the skill loads but fails at the first command.