サービスServices制作実績Works自社ツールToolsブログBlogチームTeam会社概要Company
お問い合わせ
AIコーディングCLIの使用量集計ツール「ccusage」を解説する記事のサムネイル
← ブログ一覧
AI8分

ccusageとは？Claude CodeやCodexなど複数のAIコーディングCLIの使用量とコストをまとめて見える化するOSSを試した

  • #ccusage
  • #Claude Code
  • #コスト管理

この記事でわかること

LEXIAではClaude Codeを日常的に使っており、以前「Claude Codeの料金は結局いくら？」という記事でPro・Max・API課金の違いを整理しました。今回取り上げる「ccusage」（https://github.com/ccusage/ccusage ）は、そのClaude Codeを含む複数のAIコーディングCLIが手元に残すログを読み取り、トークン使用量とコストを日次・週次・月次・セッション単位で集計してくれるOSSのコマンドラインツールです。npmパッケージとして配布されており（https://www.npmjs.com/package/ccusage ）、実際にこの検証環境で`npx ccusage@latest`を動かし、公式ドキュメント・READMEの記述と実際の挙動を突き合わせて確認しました。

  • この記事でわかること：ccusageが何を読み取り、何を計算して表示するツールか。
  • 実際に`daily`・`session`・`blocks`コマンドを動かして得られた、この環境での生の出力。
  • コストの数字がどこから来るのか：`auto`／`calculate`／`display`という3つのモードの違い。
  • 新しいCLIをサポート対象に加えるかどうかを、開発チームがどんな基準で判断しているか。
  • Claude Codeのステータスラインに組み込む手順と、standaloneで直接叩くとエラーになった実際の挙動。

ccusageとは：複数のAIコーディングCLIの使用量を1つのコマンドに集約するOSS

ccusageのnpmレジストリ上の説明文は「Analyze coding (agent) CLI token usage and costs from local data」で、作者はryoppippi氏、ライセンスはMIT、確認時点の最新バージョンは20.0.26でした。READMEによると、対応ソースはClaude Code、Codex、OpenCode、Amp、Droid、Codebuff、Hermes Agent、pi-agent、Goose、OpenClaw、Kilo、Kimi、Qwen、GitHub Copilot CLI、Gemini CLI、Antigravity、Grok Build CLI、ZCodeの18種類に及びます。ツール名こそ「cc」（Claude Code）usageですが、現在はClaude Code専用ツールではなく、手元に複数のAIコーディングCLIを併用している人向けの横断的な集計ツールに育っていることが読み取れます。

リポジトリの構成を見ると、npm配布用のTypeScript実装（`apps/ccusage`）に加えて`rust/`ディレクトリにRust製のコア実装も同梱されており、Nix経由のビルドにも対応していました。つまり単一言語のスクリプトではなく、配布経路ごとに複数の実装・ビルド手段を持つ、それなりに本格的なプロジェクトとして運用されているようです。

実際に動かしてみる：daily・session・blocksコマンドの出力

この検証環境でClaude Codeを使った直後に`npx ccusage@latest daily`を実行すると、インストール確認のプロンプトを経て、実際にその日のトークン使用量（入力・出力・キャッシュ作成・キャッシュ読み込み）と推定コスト（USD）が表として表示されました。モデル名は`claude-sonnet-5`のように実際に使用したモデルがそのまま表示され、`--json`を付けると同じ内容が`daily`配列を持つJSONとして取得できることも確認しています。

`ccusage session`では、実行中のセッションごとに同様の集計が1行ずつ表示されます。`ccusage blocks`を実行すると、Claude Codeの5時間課金ウィンドウ（セッションブロック）単位で「経過時間／残り時間」と、現在の消費ペースを前提にした残り時間分の「PROJECTED（予測）」コストが追加で表示されました。READMEやドキュメントの説明通りの構造でしたが、数値はこの検証環境でのその場の利用実績に基づくものなので、実際の値は環境ごとに異なります。

なお、ドキュメントの`docs/guide/live-monitoring.md`には「`blocks --live`によるリアルタイム監視ダッシュボードはv18.0.0で削除された」と明記されていました。ネット上にはv17系時代の`--live`オプションを紹介する記事も見つかる可能性がありますが、確認時点の最新版（20.0.26）では同オプションは存在しない点は注意が必要です。

コストはどう計算されている？auto／calculate／displayの3モード

公式ドキュメント（`docs/guide/cost-modes.md`）によると、ccusageはコスト計算に3つのモードを持ちます。既定の`auto`は、Claude Code側のログに`costUSD`という事前計算済みコストが入っていればそれを優先し、無ければトークン数からモデル料金を使って計算するハイブリッド方式です。`calculate`は事前計算済みコストを無視して常にトークン数から計算し直すモードで、異なる時期のデータを同じ基準で比較したい場合に向くとされています。`display`は逆に、事前計算済みコストが無いエントリーの扱いを変えるモードです。

価格データの出典についても明記されており、LiteLLMの価格データベースとmodels.devのモデルカタログ、および履歴価格スケジュールを組み合わせて、各利用時点のタイムスタンプに応じた単価を適用しているとのことです。`--offline`オプションを付けると、ネットワークに接続せずビルド時に埋め込まれた価格スナップショットだけを使う挙動になり、実際にこの検証環境（外部ネットワークへのアクセスが制限されている環境）でも`--offline`付きでエラーなく集計できることを確認しました。また、設定ファイルの`pricingOverrides`で、LiteLLMのデータに無い独自モデルやプロキシ経由のモデルについて、モデルごとに単価を上書きできる仕組みも用意されています。

対応ソースを決める基準と、新しいCLIが加わる仕組み

興味深かったのは、`docs/guide/source-support-qa.md`に「どんな条件を満たせば新しいコーディングCLIを対応ソースに追加するか」という判断基準が明文化されていた点です。最低限、ローカルにタイムスタンプ・セッション識別子・モデル識別子・トークン数（または記録済みコスト）が揃っている必要があり、プロンプトやトランスクリプトのテキストしか残らないツールについては「テキスト量からトークン数を推測することはしない。一見正確に見えて実際は憶測に基づくレポートになってしまうため」と明記されています。実際、同ドキュメントには「Devin CLIは利用履歴がクラウド側にしかなく、ローカルに読み取れる使用量ログが無いため非対応」という具体例も挙げられていました。

ccusageはこの原則に基づき「ローカルの読み取り専用アナライザーであり、プライベートなクラウドサービスをスクレイピングしたり、非公開APIに依存したりしない」と明言しています。対応ソースが18種類まで広がった背景には、各CLIが実際にローカルへ十分な情報を残しているかどうかを一つずつ検証して取捨選択してきた経緯があるようです。

Claude Codeのステータスラインに組み込む：standalone実行ではエラーになった

ccusageには、Claude Codeのステータスライン機能と連携する`statusline`コマンド（Beta）もあります。ドキュメントの手順に従うと、`~/.claude/settings.json`の`statusLine`に`{ "type": "command", "command": "npx -y ccusage statusline", "padding": 0 }`のような設定を追加することで、現在のセッションコスト・当日の累計コスト・5時間ブロックの残り時間とコスト・トークン消費のバーンレート・使用中のモデルを、Claude Codeの画面下部に常時表示できるとされています。

一方、このコマンドを単体で試そうと`echo '{}' | npx ccusage@latest statusline`のように実行すると、`Invalid input format: missing field `session_id` at line 1 column 2`というエラーになりました。これはccusageの不具合ではなく、`statusline`コマンドがClaude Code本体のフックから渡される`session_id`などを含むJSONを前提に動く設計だからです。つまりこの機能は、Claude Codeのステータスライン設定を経由して初めて正しく動く作りで、単体コマンドとして気軽に試せる類のものではない点は、導入前に知っておいた方がよさそうです。

まとめ

ccusageは、Claude Codeの利用料金を把握したい人だけでなく、Codex・OpenCode・Gemini CLIなど複数のAIコーディングCLIを併用している人にとって、それぞれ別々に確認するしかなかった使用量とコストを1つのコマンドで横断的に見える化してくれるツールです。実際に動かしてみると、`daily`・`session`・`blocks`といったレポートの構造、`auto`／`calculate`／`display`という3段階のコスト計算モード、LiteLLMとmodels.devを組み合わせた価格データの扱いまで、公式ドキュメントの説明と実際の挙動は一致していました。

一方で、以前存在した`blocks --live`のライブモニタリング機能がv18で削除されているなど、バージョンによって機能が変わっている点や、`statusline`コマンドはClaude Code本体のフック経由でしか正しく動かない点は、実際に試してみて初めて分かった注意点でした。Claude Codeの利用料金が気になっている場合、まずは`npx ccusage@latest`を一度実行してみるだけで、現状の消費傾向を把握できます。

参考リンク

関連記事

まずは、やりたいことを聞かせてください

「何から手をつければいいか分からない」段階でも大丈夫です。 ご相談・お見積りは無料。碧南近郊なら直接伺います。

お問い合わせ090-1742-3456