ccusage

ccusage とは

ccusage は、Claude Code をはじめ OpenAI Codex CLI・Gemini CLI などの「トークン使用量」と「概算コスト」をターミナルから確認できる CLI ツールです。Claude Code を毎日使っていると「今月いくら使ったっけ」「このセッション、トークン食いすぎでは？」が気になりますが、ccusage はローカルの使用履歴ファイル（~/.claude/projects/ 以下の JSONL）を集計してターミナル上にレポート表示してくれます。

日本人開発者の ryoppippi 氏が開発・メンテナンスしているコミュニティ製ツールで、外部 API への通信は不要・完全ローカル動作のためプライバシーやコストの心配なしで使えます。npx ccusage で即実行でき、日次 / 月次 / セッション別 / 5 時間課金ブロック別など複数のレポートモードに対応しています。

これは公式提供ではなく、有志が作った非公式ツールです。

ccusage × AI でできること

このツールを導入すると、Claude Code の使用量・コストを瞬時に把握できます。

📅 日次レポート

npx ccusage daily
→ 今日のトークン消費量と概算コストを表示

📈 月次トレンド

npx ccusage monthly
→ 月単位の使用量推移 + プラン見直し判断

🔍 セッション別分析

npx ccusage session
→ コスト効率の悪いワークフロー特定

⏱️ 5 時間ブロック管理

npx ccusage blocks
→ 課金ウィンドウ別の消費量管理

主要コマンド

ccusage が公式に提供するコマンド・オプション:

コマンド / オプション	役割
npx ccusage daily	日次レポート（デフォルト）
npx ccusage monthly	月次レポート
npx ccusage session	セッション別レポート
npx ccusage blocks	5 時間課金ブロック別レポート
--since YYYYMMDD / --until YYYYMMDD	日付範囲を絞り込み
--breakdown	モデル別の内訳を表示
--json	JSON 形式で出力（他ツール連携用）
--timezone Asia/Tokyo	日付集計のタイムゾーンを指定（例: JST）
--compact	コンパクト表示
--project <NAME>	特定プロジェクトのみ
--instances	プロジェクト / インスタンス別にグループ化

「日次・月次・セッション・ブロック」の 4 レポートモードと、表示・絞り込み・出力形式のオプションが充実しています。

ccusage について

ccusage は、日本人開発者の ryoppippi 氏が公開するコミュニティ製の Claude Code 使用量集計 CLIです。Claude Code が ~/.claude/projects/ に保存する JSONL ファイルを高速にパースし、日次・月次・セッション別・5 時間課金ブロック別のレポートをターミナル上に表示します。

外部 API への通信は不要で完全にローカルで動作します。コスト計算はオフラインの価格データに基づく概算値ですが、月次プランの見直しや「コスト食いセッション」の特定には十分です。

スペック

• 配布形態: npm パッケージ（ccusage）+ Node.js
• 認証: 不要（ローカル JSONL ファイル読み取りのみ）
• 動作環境: ターミナル CLI（完全ローカル）
• 提供元: コミュニティ実装（ryoppippi / 日本人開発者）/ MIT
• 対応範囲: Claude Code 使用量・コスト集計（日次・月次・セッション・ブロック）
• Codex / Gemini 対応: ccusage codex daily で OpenAI Codex CLI、ccusage gemini daily で Gemini CLI（実験的）の使用量も集計（いずれも本体に統合）
• 対応ツール: Claude Code・Codex・Gemini CLI のほか、複数のコーディング CLI のログ読み取りに対応（最新の対応一覧は公式ドキュメント参照）
• 公式リポジトリ: github.com/ccusage/ccusage

編集部の視点：4 つのレポート、まず使うのはこの 2 つ

ccusage には日次・月次・セッション・ブロックの 4 モードがありますが、毎日すべてを眺める必要はありません。コスト管理を目的に使うなら、編集部は次の 2 つから始めることをおすすめします。

• まず monthly（月次）から見る: 今の定額プラン（Pro / Max）が自分の使い方に見合っているか、それとも API の従量課金に切り替えた方が得かという「プランの損得」は、月単位の推移を見ないと判断できません。最初に月次で全体感をつかむのが近道です。
• 動作が止まりがちな人は blocks: Claude Code は 5 時間単位の枠で利用量が区切られるため、「午後に急に反応が重くなった／止まった」の正体が枠の使い切りであることは少なくありません。blocks で枠ごとの消費を見ておくと、上限への到達を事前に察知できます。

daily と session は、「今日は使いすぎたかも」「どの作業がトークンを食っているのか」を深掘りしたいときの道具と捉えると、4 モードの使い分けがすっきりします。

導入手順

前提条件

• Node.js
• Claude Code の使用履歴（~/.claude/projects/ 以下に JSONL ファイルが存在）

インストールと実行

インストール不要で即実行できます:

# npx で直接実行（推奨）
npx ccusage@latest

# pnpm の場合
pnpm dlx ccusage

# bun の場合
bunx ccusage

グローバルインストールする場合:

npm install -g ccusage

Claude Code 以外のツールを使う場合

ccusage 本体のサブコマンドで、Claude Code 以外のコーディング CLI も集計できます（旧 @ccusage/codex パッケージは本体統合に伴い非推奨）:

対象 CLI	実行コマンド
Claude Code	npx ccusage daily
OpenAI Codex CLI	npx ccusage codex daily
Gemini CLI（実験的）	npx ccusage gemini daily

Gemini CLI 対応は実験的な位置づけで、ログ形式の変更により挙動が変わることがあります。このほかにも複数のコーディング CLI のログ読み取りに対応しています（最新の対応一覧は公式ドキュメントを参照）。

ccusage の代替・関連ツール

ccusage は「ターミナルでレポートを出す」CLI です。コスト・使用量を別の見せ方で確認したい、あるいは Claude Code 以外の CLI もまとめて見たい場合は、目的別に次のコミュニティ製ツールが向きます（いずれも非公式・無料）。

ツール	向いている用途	実行コマンド
ccstatusline	トークン量・コストを Claude Code のステータスバーに常時表示したい（レポートを都度叩かず横目で見たい）	npx ccstatusline（npm）
tokscale	Claude Code だけでなく Codex・Gemini・Cursor・GitHub Copilot など複数の CLI を横断して使用量を集計したい	npx tokscale（npm）
codeburn	対話的な TUI ダッシュボードでコストの内訳（タスク・モデル・プロジェクト別）を掘りたい	npx codeburn（npm）

役割で分けると、ccusage は「日次・月次の振り返りレポート」、ccstatusline は「作業中の常時表示」、tokscale は「複数 CLI の横断集計」、codeburn は「内訳を掘る TUI」です。まず ccusage で全体感をつかみ、物足りない軸が出たら上記を足すのが無理のない順序です。

ここで挙げたツールはいずれも有志による非公式のコミュニティ製ツールです。仕様や対応範囲は各 GitHub リポジトリの最新情報を確認してください。

注意事項

• Claude Code が ~/.claude/projects/ に保存する JSONL ファイルを読み取ります。Claude Code を使用していない環境では動作しません。
• コスト計算はオフラインの価格データに基づく概算値です。正確な請求額は Anthropic のダッシュボードで確認してください。
• 価格データはパッケージに内包されているため、Anthropic 側で価格改定があった場合、最新版へのアップデートが必要です。
• 詳細・最新情報は GitHub リポジトリ を参照してください。
• 本ツールはコミュニティ実装（ryoppippi 氏）です。Anthropic 社が公式に提供するものではありません。