ccusage - Claude Code使用状況分析ツール

プロジェクト概要

ccusageは、Claude CodeのローカルJSONLファイルから使用状況データを分析するためのCLIツールです。このプロジェクトは@ryoppippiによって開発され、Claude Codeの使用コストを追跡する記事に触発されました。

主な機能

📊 多様なレポートタイプ

• 日次レポート: 日付ごとにトークン使用量とコストを集計
• 月次レポート: 月ごとにトークン使用量とコストを集計
• セッションレポート: 会話セッションごとに使用状況をグループ化して表示
• 5時間ブロックレポート: 5時間ごとの課金ウィンドウに基づいたレポート
• ステータスライン: フック用のコンパクトなステータスライン（ベータ版）

🎯 強力なフィルタリングと分析機能

• 日付フィルタリング: --sinceと--untilを使用して日付範囲でレポートをフィルタリング
• プロジェクト分析: プロジェクト/インスタンスごとにグループ化し、特定のプロジェクトのフィルタリングをサポート
• モデルコスト内訳: モデルごとのコスト内訳
• タイムゾーンとローカライゼーション: UTCタイムゾーンと日本語ローカライズ形式をサポート

🎨 美しい出力と表示

• 自動応答型レイアウトを備えたカラーテーブル形式で表示
• スマートテーブル：狭いターミナル（100文字未満）では自動的にコンパクトモードになり、基本的な列を表示
• コンパクトモード：--compactフラグを使用して強制的にコンパクトなテーブルレイアウトにし、スクリーンショットや共有に最適
• 強化されたモデル表示：モデル名を箇条書きリストで表示し、可読性を向上

💰 コスト追跡機能

• 日次/月次/セッションごとのコストをドルで表示
• キャッシュトークンサポート：キャッシュ作成トークンとキャッシュ読み取りトークンを個別に追跡および表示
• オフラインモード：--offlineを使用して、ネットワーク接続がない場合にプリキャッシュされた価格データを使用（Claudeモデルのみ）

⚡ リアルタイム監視

• リアルタイム使用状況ダッシュボード
• リアルタイム監視：ccusage blocks --live

インストールと使用方法

クイックスタート（インストール不要）

ccusageはパッケージサイズが非常に小さいため、インストールせずに直接実行できます。

# bunxを使用（推奨、高速）
bunx ccusage

# npxを使用
npx ccusage@latest

# denoを使用（セキュリティフラグ付き）
deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest

グローバルインストール

# npmでグローバルインストール
npm install -g ccusage

# bunでグローバルインストール
bun install -g ccusage

# その後、実行
ccusage

開発環境

# リポジトリをクローン
git clone https://github.com/ryoppippi/ccusage.git
cd ccusage

# 依存関係をインストール
bun install

# ツールを実行
bun run report [subcommand] [options]

基本的な使用方法

日次レポート

# すべての日次使用状況を表示
ccusage daily

# 日付範囲でフィルタリング
ccusage daily --since 20250525 --until 20250530

# カスタムClaudeデータディレクトリを使用
ccusage daily --path /custom/path/to/.claude

# JSON形式で出力
ccusage daily --json

# モデルごとのコスト内訳
ccusage daily --breakdown

# UTCタイムゾーンを使用
ccusage daily --timezone UTC

# 日本語ローカライズを使用
ccusage daily --locale ja-JP

プロジェクト分析

# プロジェクト/インスタンスごとにグループ化
ccusage daily --instances

# 特定のプロジェクトにフィルタリング
ccusage daily --project myproject

# 組み合わせて使用
ccusage daily --instances --project myproject --json

セッションレポート

# すべてのセッションを表示
ccusage session

# 最終アクティビティ日付でセッションをフィルタリング
ccusage session --since 20250525

# フィルタを組み合わせる
ccusage session --since 20250525 --until 20250530 --path /custom/path

# JSON形式で出力
ccusage session --json

リアルタイム監視

# リアルタイム使用状況ダッシュボード
ccusage blocks --live

# 5時間課金ウィンドウ
ccusage blocks

# ステータスライン（ベータ版）
ccusage statusline

コンパクトモード

# 強制的にコンパクトなテーブルモード
ccusage --compact

# コンパクトな月次レポート
ccusage monthly --compact

コマンドオプション

すべてのコマンドは以下のオプションをサポートしています。

• -s, --since <date>: 指定した日付以降でフィルタリング（YYYYMMDD形式）
• -u, --until <date>: 指定した日付以前でフィルタリング（YYYYMMDD形式）
• -p, --path <path>: Claudeデータディレクトリのカスタムパス（デフォルト：~/.claude）
• -j, --json: 結果をテーブルではなくJSON形式で出力
• -h, --help: ヘルプ情報を表示
• -v, --version: バージョンを表示

出力例

日次レポート出力

╭──────────────────────────────────────────╮
│                                          │
│ Claude Code Token Usage Report - Daily  │
│                                          │
╰──────────────────────────────────────────╯
┌──────────────────┬──────────────┬───────────────┬──────────────┬────────────┐
│ 日付             │ 入力トークン │ 出力トークン  │ 合計トークン │ コスト (USD) │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ 2025-05-30       │ 277          │ 31,456        │ 31,733       │ $17.45     │
│ 2025-05-29       │ 959          │ 39,662        │ 40,621       │ $16.37     │
│ 2025-05-28       │ 155          │ 21,693        │ 21,848       │ $8.33      │
├──────────────────┼──────────────┼───────────────┼──────────────┼────────────┤
│ 合計             │ 11,174       │ 720,366       │ 731,540      │ $336.17    │
└──────────────────┴──────────────┴───────────────┴──────────────┴────────────┘

セッションレポート出力

╭───────────────────────────────────────────────╮
│                                               │
│ Claude Code Token Usage Report - By Session  │
│                                               │
╰───────────────────────────────────────────────╯
┌──────────────────────────────┬──────────────┬───────────────┬──────────────┬────────────┬───────────────┐
│ プロジェクト / セッション    │ 入力トークン │ 出力トークン  │ 合計トークン │ コスト (USD) │ 最終アクティビティ │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ my-project                   │ 2,775        │ 186,645       │ 189,420      │ $98.40     │ 2025-05-26    │
│ └─ session-abc123...         │              │               │              │            │               │
│ another-project              │ 1,063        │ 41,421        │ 42,484       │ $20.08     │ 2025-05-29    │
│ └─ session-def456...         │              │               │              │            │               │
├──────────────────────────────┼──────────────┼───────────────┼──────────────┼────────────┼───────────────┤
│ 合計                         │ 11,174       │ 720,445       │ 731,619      │ $336.38    │               │
└──────────────────────────────┴──────────────┴───────────────┴──────────────┴────────────┴───────────────┘

技術アーキテクチャ

依存要件

• Bunランタイム
• Claude Code使用履歴ファイル（~/.claude/projects/**/*.jsonl）

プロジェクト構造

ccusage/
├── commands/
│   ├── daily.ts        # 日次レポートコマンド
│   └── session.ts      # セッションレポートコマンド
├── data-loader.ts      # JSONLデータロードロジック
├── index.ts           # CLIエントリポイント
├── logger.ts          # ロギング設定
├── utils.ts           # 共有ユーティリティ
└── package.json

開発とテスト

# テストを実行
bun test

# 型チェック
bun run typecheck

# コードチェック
bun run lint

# コードをフォーマット
bun run format

連携機能

🔌 MCP連携

他のツールとの連携のためのモデルコンテキストプロトコルサーバーを内蔵

まとめ

ccusageは、Claude Codeユーザー向けにトークン使用状況と関連コストを分析・追跡するために設計された、強力で使いやすいCLIツールです。その軽量な設計、豊富な機能セット、そして美しい出力は、Claude Codeの使用を最適化し、コストを管理したい開発者にとって理想的な選択肢となります。