Workflow & Core Tools · daymade/claude-code-skills

claude-usage-analyst

Name: claude-usage-analyst
Author: daymade/claude-code-skills

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.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Data source is local ccusage: analyze_claude_usage.py does not parse logs itself; instead, it uses subprocess to call `ccusage claude daily/blocks --json` to fetch JSON and extract metrics—the skill's value lies in 'interpreting ccusage figures into plain human language'.

daymade-claude-code/claude-usage-analyst/scripts/analyze_claude_usage.py

proc = subprocess.run( ["ccusage", "claude", *args, "--json"],

run_ccusage first checks shutil.which('ccusage'); if missing, it raises an error prompting to run npm install -g ccusage@latest.

Window semantics: by default, --since/--until targets today in the selected timezone (default: Asia/Shanghai); historical comparison requires an explicit --since, otherwise rank/median only reflects a single day.

daymade-claude-code/claude-usage-analyst/SKILL.md

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

In summarize(), daily[-1] or date==until selects the target day, and the before list is used for 'historical median prior to target day' comparison.

Model comparison supports aliases: --model-a/--model-b performs substring matching against target day modelBreakdowns (default fable vs opus-4-8), outputting token ratio vs cost ratio to correct the misconception that 'more tokens always means more expensive'.

daymade-claude-code/claude-usage-analyst/SKILL.md

python3 scripts/analyze_claude_usage.py --model-a fable --model-b opus-4-8

find_model uses needle.lower() in name.lower(); the SKILL explicitly specifies pointing out unit price differences when 'tokens are comparable but cost is higher'.

5-hour blocks are provided by the ccusage blocks command (approximate quota window grouping); the script skips isGap, retains only target-day blocks, and outputs start/end times, model counts, entries, tokens, cost, and cache ratio.

daymade-claude-code/claude-usage-analyst/SKILL.md

4. 5-hour block table when quota exhaustion is discussed.

explanation-guide.md emphasizes that the 5-hour block is an approximation by ccusage grouping, not an official subscription quota contract.

Separation of explanation and evidence layers: the SKILL mandates that numerical conclusions must be grounded in ccusage/analyzer outputs. Cache must be explained (reads also exert usage pressure). When plan rules are unknown, phrasing such as 'quota-like pressure/ccusage estimated' must be used, with final answers structured according to explanation-guide.md.

daymade-claude-code/claude-usage-analyst/SKILL.md

Explain cache clearly: cache read tokens are still usage/quota pressure even though the user did not type those words.

Evidence rules are all centered on 'do not extrapolate local token counts into official billing statements'.

2Core Capabilities

01Single-day/range usage statistics: total tokens, estimated cost, input/output/cache create/cache read + cost/usage ranking within the window

02Model mix breakdown and two-model comparison (token ratio + cost ratio, alias substring matching)

035-hour block perspective to explain quota depletion (start/end, models, entries, tokens, cost)

04Timezone accuracy: --timezone (full zoneinfo name) applies to date windows and block start/end conversions

05Dual output formats: human-readable Markdown table / --json structured data

06Plain-language explanations for non-technical users (explanation-guide: cache read > 80% means the agent is repeatedly reading context rather than user typing heavily)

3External Dependencies

Kind	Dependency / Endpoint
cli	ccusage（第三方 npm CLI，用量统计）
package	ccusage@latest（npm 全局安装）
cli	python3（zoneinfo 需系统 tz 数据）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Execute local scripts or commands: scripts/analyze_claude_usage.py
网络端点: Declared external network access: (Only when ccusage is missing) npm install -g ccusage@latest / npx ccusage@latest —— from npm

Audit Notes: The skill's own script only invokes local ccusage via subprocess and parses public usage metrics (token counts, estimated costs, model names, time blocks), requiring zero network calls, zero credential reading, and zero file writes—it does not access key-bearing files like ~/.claude/settings/.claude.json. The yellow rating stems from two factors: 1) Dependency on the third-party npm package ccusage (supply chain: installed from registry.npmjs.org, whose package behavior is not auditable within this repository; pinning versions before installing is recommended); 2) Data read targets local session usage logs (privacy surface, though not a credential surface). If ccusage exhibits network upload or key-reading behavior during use (which cannot be verified by this repo), it should be escalated to orange.

5Second-Pass Verification

[ok] 无网络外发（脚本自身） — 无 urllib/requests/socket；唯一外部动作是 npm install ccusage 的安装提示（用户/agent 执行）
[ok] 无凭证读取 — 无 environ/getenv/settings/.claude.json 读取；ccusage 侧读取范围不可在本仓审计（已在 reason 注明）
[ok] 无写文件 — 脚本只 print（stdout），无文件写入
[ok] 数字字段映射准确 — cacheCreationTokens/cacheReadTokens/cost 等字段名与 ccusage JSON 语义一致；model_total 明确含 cache 系 token
[ok] ‘ccusage 不是官方账单’边界 — SKILL evidence rules 与 explanation-guide caveats 双重声明 estimated/quota-like 措辞要求

6Verdict & Scenarios

Evidence-driven: all figures originate from ccusage JSON without guessing or fabrication, maintaining a dedicated explanation layer

Honest handling of cache and quota semantics (cache reads also exert pressure; unknown rules use qualified phrasing)

Addresses common pain points: why quota burned out, which model is expensive, and 5-hour block analysis

Lightweight, read-only tool with zero writes and zero credentials, featuring timezone support and two-model comparison

Best for: Ideal for Claude Code users troubleshooting 'where today's tokens/money went, whether a specific model was exceptionally expensive, or how the 5-hour quota was consumed'; works out of the box for users with ccusage installed, with results directly applicable to tuning model routing and caching strategies.

Not for: Not suitable for financial contexts requiring official billing precision (consult the Anthropic console instead); not suitable for restricted environments where ccusage is absent and npm package installations are disallowed; not suitable for analyzing Claude.ai web chats (not in local logs) or non-Claude usage.

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload claude-usage-analyst.tar.gz

sha256: 009defcb5a1b30df…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.