claude-usage

Claude の使用状況

Claude Code セッションの正確なトークン使用量とコストを報告します。JSONL ファイルを直接解析し、親セッションとサブエージェントのサイドチェーンから正確な数値を算出します。

このツールが必要な理由

ccusage（v18 以降。スター数 10.6k の標準的なコミュニティツール）は、ヘビーユーザーの出力トークン数を 77～94％過少に計上します。

ソース	出力トークン数	備考
Raw JSONL（全ファイル）	1,076,691	実際の値
Raw JSONL（日付でフィルタリング）	412,987	適切にフィルタリング済み
ccusage --timezone UTC	93,960	77％過少に計上
ccusage default	62,375	94％過少に計上

重なり合う 3 つのバグ：

1. {session-uuid}/subagents/{agent-id}.jsonl にあるサブエージェントのファイルを無視します。Agent Teams を使用する場合、通常の日でも 132 個のファイルが漏れます
2. UTC のエントリータイムスタンプと現地時間のフィルタリングの間で、タイムゾーンの扱いに混乱があります
3. 親ファイル内のエントリーを取りこぼします。UTC を指定しても、実際のトークン数の 23％しか報告されません

このスクリプトはすべての JSONL ファイルを読み込み、正確な合計を算出します。

---

使い方

# Today's usage (default)
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py

# Last 7 days, broken down by day
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --since 7d

# Weekly breakdown for the past month
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --by week --since 30d

# Per-model breakdown
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --by model --since 7d

# Per-session with human-readable summaries
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --by session --since 1d

# Per-project breakdown
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --by project --since 7d

# Filter to one project
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --project Thera --since 30d

# Custom date range
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --since 2026-02-01 --until 2026-02-28

# JSON output (pipe to jq)
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --since 7d --json | jq '.grand_total'

# CSV output
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --since 7d --csv

# Compare against ccusage (shows delta)
python3 ~/.claude/skills/claude-usage/scripts/claude_usage.py --compare

# PDF report (dark editorial, CTO-ready)
python3 ~/.claude/skills/claude-usage/scripts/claude_usage_report.py --since 30d

# PDF with custom output path
python3 ~/.claude/skills/claude-usage/scripts/claude_usage_report.py --since 30d -o ~/Desktop/feb-usage.pdf

# HTML only (no Playwright needed)
python3 ~/.claude/skills/claude-usage/scripts/claude_usage_report.py --since 7d --html

---

出力列

列	説明
Input	入力トークン（入力料金で課金）
Output	応答トークン（最も高額なカテゴリ）
CacheW	キャッシュ書き込みトークン（cache_creation_input_tokens）
CacheR	キャッシュ読み取りトークン（入力トークンより大幅に低価格）
Total	4 種類すべてのトークンの合計
Cost	ハードコードされた料金表に基づく推定 USD

---

集計モード（--by）

モード	グループ化の単位	キーの例
day（デフォルト）	現地タイムゾーンの暦日	2026-02-20
week	ISO 週番号	2026-W08
month	月	2026-02
session	セッション UUID（sessions-index.json の概要に対応付け）	8a6c801a Working on Claudicle...
model	モデル名	claude-opus-4-6
project	プロジェクトディレクトリ（パスにデコード）	~/Desktop/Programming

---

料金表

料金は claude_usage.py の先頭にある PRICING dict にハードコードされています。Anthropic が料金を変更した場合は更新してください。キーはモデル名の部分文字列で、最も具体的なものから順に照合されます。

現在のデフォルト料金（トークン 100 万個あたりの USD、2026-02-21 に確認済み）：

モデル	入力	出力	キャッシュ書き込み（1 時間）	キャッシュ読み取り
Opus 4.5 / 4.6	$5.00	$25.00	$10.00	$0.50
Opus 4.0 / 4.1	$15.00	$75.00	$30.00	$1.50
Sonnet 4.x	$3.00	$15.00	$6.00	$0.30
Haiku 4.5	$1.00	$5.00	$2.00	$0.10
Sonnet 3.7 / 3.5	$3.00	$15.00	$6.00	$0.30
Haiku 3.5	$0.80	$4.00	$1.60	$0.08
Opus 3	$15.00	$75.00	$30.00	$1.50
Haiku 3	$0.25	$1.25	$0.50	$0.03

キャッシュ書き込み列は 1 時間の料金（基本入力料金の 2 倍）を示します。Claude Code は 1 時間のプロンプトキャッシュのみを使用します。JSONL の cache_creation サブオブジェクトに TTL の内訳が含まれている場合は、5 分の料金（基本入力料金の 1.25 倍）もサポートされます。

---

タイムゾーンの処理

JSONL のタイムスタンプは UTC です。スクリプトは --since／--until フィルターを適用する前に、システムの現地タイムゾーン（または --tz America/New_York）に変換します。これにより、UTC の日付と現地の日付が異なるときに ccusage がエントリーを取りこぼす原因となる、日付の境界付近での混乱を防ぎます。

---

データソース

~/.claude/projects/{encoded-path}/ にある JSONL ファイル：

• 親セッション：{session-uuid}.jsonl
• サブエージェントのサイドチェーン：{session-uuid}/subagents/{agent-id}.jsonl
• セッションメタデータ：sessions-index.json（--by session 用の概要）

スクリプトはストリーミングで 1 行ずつ読み込むため、300MB を超えるファイルもメモリ使用量 O(1) で処理できます。

---

PDF レポート

claude_usage_report.py は、Crimson Pro と JetBrains Mono のタイポグラフィ、ミノア文明をイメージしたゴールドのアクセント、棒グラフ、色分けされた積み上げ棒グラフによるモデル分布、トークン構成の内訳、詳細な表を備えた、ダークなエディトリアル調の PDF を生成します。経営層との共有を想定して設計されています。

Playwright が必要です（uv pip install --system playwright && playwright install chromium）。Chromium を使用して、ピクセル単位で正確な CSS レンダリングを行います。これは Aldea Slide Deck スキルと同じエンジンです。--html フラグを指定すると、HTML 出力にフォールバックします。

---

注意事項

• 推定精度：約 95％です。 残る誤差は、データレジデンシーによる倍率（米国内のみでの推論では 1.1 倍、追跡対象外）と、ストリーミングのチャンク境界における潜在的なエッジケースに起因します。
• ストリーミングのチャンクは、メッセージ ID ごとに最後の値を採用する方法で重複排除されます。チャンク間で output_tokens は単調増加するため、各メッセージ ID で最後のチャンクだけが正しい値を持ちます。重複排除を行わない場合、コストが 2～5 倍に過大計上されていました。
• コストは料金表に基づいて推定されます。バッチ割引やプロモーション価格により、Anthropic の請求額とは異なる場合があります。
• キャッシュ書き込みの料金には、デフォルトで 1 時間の料金が使用されます（Claude Code のキャッシュモード）。JSONL に cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens が含まれる場合は、それぞれの料金が適用されます。
• 合成エントリ（model: "<synthetic>"）と請求エラーのエントリ（トークン数がすべてゼロ）は、自動的に除外されます。
• 不正な形式の JSON 行と重複したストリーミングチャンクは集計され、出力のフッターに報告されます。
• zoneinfo モジュールを使用するため、Python 3.9 以降が必要です。
• PDF レポートには、Chromium を含む Playwright が必要です（playwright install chromium）。完全な料金表、計算式、信頼度バッジを含む「料金算出方法」セクションが追加されます。