ホーム / 全スキル / ワークフロー＆基本ツール / claude-usage-analyst
English (EN)简体中文 (ZH)日本語 (JA)
ワークフロー＆基本ツール · daymade/claude-code-skills

claude-usage-analyst

ccusageのエビデンスを活用し、Claude CodeおよびClaude Desktop Codeのトークン使用量、コスト、クォータ消費、モデル混成比率、キャッシュ読み書き、5時間ブロック消費を分析します。Claudeのクォータが枯渇した理由、fable/opus/sonnetなどのモデルが異常に高コストかどうかの確認、本日または過去のトークン消費量の把握、ローカルのClaude Code CLI/Desktop使用量に関するわかりやすい説明が必要な場合に使用します。

L4 高権限 · 段階的認可と監査V1 コミット固定コマンド実行ネットワーク通信Dual-pass Audit
Author daymadeGitHub daymade/claude-code-skills ↗Stars 1385License MIT（仓库根 LICENSE：Copyright (c) 2025 daymade；GitHub API spdx MIT）Commit d5c4678cb5
管理レベルは Skill の能力と推奨統制措置を示すものであり、品質や安全性の認証、利用可否の判定ではありません。使用の可否はユーザーおよび管理者が決定します。Agent 環境によって制約が異なるため、自動保護を仮定しないでください。第三者製 Skill の著作権は原著作者に帰属し、利用リスクは利用者が負います。

1仕組みと動作原理

データソースはローカルのccusage：analyze_claude_usage.pyはログ自体をパースせず、subprocess経由で`ccusage claude daily/blocks --json`を呼び出してJSONを取得・抽出します。スキルの価値は「ccusageの数値を読み取り、平易な言葉で説明すること」にあります。

daymade-claude-code/claude-usage-analyst/scripts/analyze_claude_usage.py
proc = subprocess.run( ["ccusage", "claude", *args, "--json"],
run_ccusageはまずshutil.which('ccusage')を検証し、未検出時はエラーを出力してnpm install -g ccusage@latestの実行を案内します。

期間ウィンドウのセマンティクス：デフォルトでは--since/--untilに指定タイムゾーン（デフォルト：Asia/Shanghai）の「本日」が適用されます。過去比較には明示的な--sinceの指定が必要であり、指定がない場合rank/medianは単日のみを記述します。

daymade-claude-code/claude-usage-analyst/SKILL.md
Default `--since/--until` is today in the selected timezone.
summarize()内ではdaily[-1]またはdate==untilによって対象日を抽出し、beforeリストを「対象日より前の過去中央値」との比較に使用します。

モデル比較はエイリアスに対応：--model-a/--model-bで対象日のmodelBreakdowns内を部分一致検索（デフォルト：fable対opus-4-8）し、トークン比とコスト比を出力して「トークン量が多い＝高額」という誤解を是正します。

daymade-claude-code/claude-usage-analyst/SKILL.md
python3 scripts/analyze_claude_usage.py --model-a fable --model-b opus-4-8
find_modelはneedle.lower() in name.lower()を使用します。SKILLでは「トークン量が同等でもコストが高い」場合に単価の差を指摘することを明記しています。

5時間ブロックはccusage blocksコマンドにより提供（クォータウィンドウの近似グループ化）。スクリプトはisGapをスキップして対象日のブロックのみを保持し、開始/終了時刻、モデル数、エントリ数、トークン数、コスト、キャッシュ比率を出力します。

daymade-claude-code/claude-usage-analyst/SKILL.md
4. 5-hour block table when quota exhaustion is discussed.
explanation-guide.mdでは、5時間ブロックはccusageによる近似グループ化であり、サブスクリプションの公式クォータ契約ではないことを強調しています。

解説層とエビデンス層の分離：SKILLでは数値結論を必ずccusage/analyzerの出力に基づくものと規定しています。キャッシュの説明（readも利用負荷に含まれる）を行い、プラン詳細が不明な場合は「quota-like pressure/ccusage estimated」といった限定的な表現を用い、最終回答は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.
エビデンスルールはすべて「ローカルのトークン数を公式の請求基準に外挿して解釈しない」ことを徹底しています。

2コア機能

01単日/期間の使用量統計：total tokens、estimated cost、input/output/cache create/cache read、およびウィンドウ内のコスト/使用量ランキング
02モデル混成の内訳と2モデル間比較（トークン比率＋コスト比率、エイリアス部分一致対応）
03クォータ枯渇を解説する5時間ブロック視点（開始/終了、モデル、エントリ数、トークン、コスト）
04タイムゾーンの正確性：--timezone（zoneinfo完全名）による日付ウィンドウおよびブロック開始/終了日時の変換
05選べる2種類の出力形式：可読性の高いMarkdownテーブル / --json構造化データ
06非技術者向けの平易な解説（explanation-guide：cache read > 80% はユーザーが大量に入力したのではなくエージェントがコンテキストを反復読み込みしている状態を意味するなど）

3外部依存関係

KindDependency / Endpoint
cliccusage（第三方 npm CLI，用量统计）
packageccusage@latest（npm 全局安装）
clipython3（zoneinfo 需系统 tz 数据）

4推奨統制措置と判定根拠

安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
  • scripts/: ローカルスクリプトまたはコマンドの実行: scripts/analyze_claude_usage.py
  • 网络端点: 外部ネットワークアクセスの宣言: （ccusage未検出時のみ）npm install -g ccusage@latest / npx ccusage@latest —— npmより取得
監査ノート： スキル自体のスクリプトはsubprocess経由でローカルのccusageを呼び出し、公開利用指標（トークン数、推定コスト、モデル名、タイムブロック）を解析するのみで、ネットワークアクセスなし、認証情報読み取りなし、ファイル書き込みなしで動作し、~/.claude/settings/.claude.jsonなどのキー情報を含むファイルには一切触れません。Yellow指定の理由は2点あります：①サードパーティnpmパッケージ「ccusage」への依存（サプライチェーン：registry.npmjs.orgからインストールされ、パッケージ内部の挙動は本リポジトリで監査できないため、バージョンを固定してのインストールを推奨）；②読み取り対象がローカルセッションのusageログであること（認証情報ではないもののプライバシー対象）。万一ccusageの実行中に外部ネットワークへの送信やAPIキーの読み出し等の挙動が見られた場合（本リポジトリでは検証不可）、Orangeとして扱う必要があります。

5二重目の独立検証

  • [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 措辞要求

6結論

  • エビデンス重視：全数値はccusageのJSONに由来し、推測や捏造を排除しつつ解説層を独立して構成
  • キャッシュおよびクォータの正確な解釈（cache readも負荷として計上、不明なルールには限定的な表現を使用）
  • 日常の重大な課題に対応：クォータ枯渇の原因究明、高額モデルの特定、5時間ブロック単位の分析
  • 書き込み不要・認証情報不要の軽量読み取り専用ツールで、タイムゾーンと2モデル比較に対応
    • 最適な用途： Claude Codeユーザーが「本日のトークン/費用の内訳、特定モデルが異常に高額か、5時間クォータがどう消費されたか」を自己診断する用途に適しています。ccusage導入済み環境なら即座に利用可能で、分析結果をモデルルーティングやキャッシュ戦略の改善に直接役立てられます。
    不向きな用途： 公式請求レベルの厳密さを求める財務用途（Anthropicコンソールを参照してください）；ccusageが未導入かつnpmパッケージのインストールが禁止されている制限環境；Claude.ai Web版チャット（ローカルログ対象外）やClaude以外のモデル利用の分析には適していません。
    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
    Agent はこの JSON ガイドから自動的にダウンロードして検証します。
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit d5c4678cb5.