ccusageでClaude Codeの使用量とコストをローカル集計する
ccusageはClaude Codeのローカルログから日次・セッション別・5時間ブロック別に使用量とコストを集計するCLIです。コマンド、コスト計算モード、/usageとの違いをまとめます。
ccusageは、Claude Codeがローカルに残した使用量データを読み取り、日次・週次・月次・セッション別・5時間ブロック別のレポートにまとめるCLIです。インストールは不要で、npx ccusage@latestだけで動きます。
Claude Code標準の/usageが「いまのセッション」と「直近24時間・7日の按分」を見るものなのに対し、ccusageは過去の履歴を日付やセッションで並べ直せます。月末に「どの日にいくら使ったか」を振り返りたいときに向く道具です。
ccusageとは何か
ccusageは、コーディングエージェントCLIのローカルデータからトークン使用量とコストを集計するツールです。READMEの副題は「Analyze coding (agent) CLI token usage and costs from local data」で、Claude Code以外にもCodex、OpenCode、Gemini CLIなど複数のエージェントを同じ形式で集計できます。ライセンスはMITです。
仕組みは単純です。Claude Codeはセッションごとの会話記録をJSONLファイルとして保存しており、ccusageはそこに含まれるトークン数と(あれば)コスト情報を読んで表にします。ネットワーク経由でアカウントの請求情報を取りに行くわけではありません。
この前提から、次の2点が決まります。
- 集計できるのは、そのマシンに残っているログだけです。他の端末やclaude.aiでの利用は入りません
- 保存期間を過ぎて削除されたセッションは集計できません。Claude Code側の
cleanupPeriodDaysは既定30日で、期間を過ぎたセッションデータは起動時に削除されます
月をまたいで振り返りたい場合は、削除される前に--jsonで書き出しておくのが安全です(手順は後述の「JSON出力で保存する」にあります)。
実行してみる:最初の1コマンド
Node.jsが入っていれば、次の1行で日次レポートが出ます。READMEはnpx ccusage@latestを最初の手順として示しています。
npx ccusage@latest引数なしの実行は、検出できるすべてのエージェントを日別にまとめた表になります。Claude Codeだけを見たいときは、claudeを挟んだ形にします。
npx ccusage@latest claude dailyREADME上のパッケージランナーはnpxのほかにbunx、pnpm dlx、pnpx、Nixのnix runが並びます。毎回使うならbunxのようにパッケージをキャッシュするランナーのほうが2回目以降は速くなる、とREADMEにあります。
Claude Code専用か、全エージェント統合か
サブコマンドの付け方で集計の範囲が変わります。
| 実行する形 | 集計の範囲 |
|---|---|
ccusage daily | 集計の範囲検出できた全ソースを日別に統合 |
ccusage claude daily | 集計の範囲Claude Codeだけ |
ccusage daily --by-agent --json | 集計の範囲全ソースを統合し、エージェント別に分けてJSON出力 |
Claude Codeだけを数えたいのにccusage dailyを使うと、CodexやGeminiのログも同じ表に混ざります。Claude Code単体の数字が欲しいなら、ccusage claude始まりの形を選びます。
日次・月次・セッション別のレポートを使い分ける
基本の集計軸は4つです。READMEの「Basic usage」に沿ってまとめます。
| コマンド | 軸 | 向く場面 |
|---|---|---|
ccusage claude daily | 軸日 | 向く場面1日ごとの消費の山を見る |
ccusage claude weekly | 軸週 | 向く場面週単位で上限や予算と照らす |
ccusage claude monthly | 軸月 | 向く場面月次のコストをまとめる |
ccusage claude session | 軸会話単位 | 向く場面どの会話が重かったかを特定する |
期間を絞るオプションも用意されています。
# 期間を指定する
npx ccusage@latest claude daily --since 2026-09-01 --until 2026-09-30
# 今日・今週・今月だけを見る
npx ccusage@latest claude daily --last 1
npx ccusage@latest claude weekly --last 1
npx ccusage@latest claude monthly --last 1--last 1は、日次なら今日、週次なら今週、月次なら今月だけを返します。日付のグルーピングはタイムゾーンで結果が変わるため、--timezone UTCのように明示もできます。
プロジェクト別に分ける
リポジトリごとにコストを見たいときは--instancesを使います。
# プロジェクト(インスタンス)ごとにグループ化
npx ccusage@latest claude daily --instances
# 特定プロジェクトだけに絞る
npx ccusage@latest claude daily --instances --project myproject --jsonClaude Codeのログは~/.claude/projects/<project>/以下にプロジェクト単位で置かれるので、この軸と対応が取れます。保存先の仕組みはClaude Codeのセッションエクスポートとトランスクリプトの保存場所にまとまっています。
モデル別の内訳を出す
--breakdownを付けると、モデル別のコスト内訳が展開されます。OpusとSonnetを混ぜて使っているときに、どちらが日次コストを押し上げているかを切り分けられます。
npx ccusage@latest claude daily --breakdownキャッシュ作成とキャッシュ読み取りのトークンは別列で表示されます。キャッシュが効いているかどうかは、この列の比率からも読めます。
5時間ブロックで使用量を見る
ccusage blocksは、Claude Codeの5時間の請求ウィンドウに沿って使用量をまとめるレポートです。5時間の窓ごとに消費ペースを確認したいときに使います。
# 全ブロックを一覧する
npx ccusage@latest blocks
# いま進行中のブロックだけを見る
npx ccusage@latest blocks --active
# 直近3日分のブロック
npx ccusage@latest blocks --recentccusageの公式ドキュメントでは、ブロックの仕組みを次のように説明しています。
- ブロックの開始は最初のメッセージで決まる
- 継続時間は開始から5時間
- 前のブロックが期限切れになったあと、次の活動で新しいブロックが始まる
- ブロックの境界はタイムゾーンによる差が出ないよう、UTCで計算される
進行中のブロックには、残り時間、1分あたりのトークン消費ペース(Rate)、このペースが続いた場合の最終トークン数(Projected)が表示されます。
トークン上限を引いて警告を出す
--token-limitで上限値を渡すと、上限に近づいたブロックに警告が付きます。maxを渡すと、過去のブロックのうち最大だったものが上限になります。
# 上限を明示する
npx ccusage@latest blocks --token-limit 500000
# 過去最大のブロックを上限にする
npx ccusage@latest blocks -t maxこの上限値はユーザーが自分で置くしきい値で、Anthropic側の実際の使用量上限そのものではありません。実際の上限は/usageのプラン使用量バーが正です。ブロックの長さは--session-lengthで変えられますが、5時間以外にしたブロックはClaudeの請求ウィンドウとは対応しなくなります。
ライブ監視はv18で廃止された
古い記事にはccusage blocks --liveでリアルタイム監視する手順が出てきます。このオプションはv18.0.0で削除されており、v17.x系でのみ使えます。公式ドキュメントはリアルタイムの確認にstatuslineコマンドを使うよう案内しています。
コストの計算方法:3つのモード
ccusageの数字を請求や/usageと比べるとき、最初に確認すべきは--modeです。Claude Codeのログにはトークン数に加えて、事前に計算されたコスト(costUSD)が入っていることがあります。ccusageはこれをどう扱うかを3つのモードで切り替えます。
| モード | 動作 | 向く用途 |
|---|---|---|
auto(既定) | 動作costUSDがあればそれを使い、無ければトークン数から計算 | 向く用途通常の集計 |
calculate | 動作costUSDを無視し、全件をトークン数と単価から計算 | 向く用途期間をまたいだ一貫した比較 |
display | 動作costUSDだけを表示。無い行は$0.00 | 向く用途請求との突き合わせ |
calculateの単価は、LiteLLMのデータベースやmodels.devのカタログ、内蔵の過去料金表から引かれ、各イベントのタイムスタンプで時期ごとの単価が適用されます。計算式は、入力・出力・キャッシュ作成(5分/1時間)・キャッシュ読み取りのトークン数にそれぞれの単価を掛けて合計する形です。
# 全期間を同じ方法で計算し直す
npx ccusage@latest claude monthly --mode calculate --breakdown
# 記録済みコストだけを表示する(欠けている行は$0.00になる)
npx ccusage@latest claude daily --mode displaydisplayは欠けた行を$0.00と表示するため、合計が小さく見えることがあります。autoとdisplayで合計が食い違ったら、costUSDが記録されていない行があるサインです。
価格はオンラインで取得するため、ネットワークが使えない環境では--offline(短縮形-O)でキャッシュ済みの料金データを使います。
JSON出力で保存する
--jsonを付けると、表ではなくJSONで出力されます。保存期間の30日を過ぎる前に、月次で書き出しておく用途に向きます。
# 月次レポートをファイルに残す
npx ccusage@latest claude monthly --json > usage-2026-09.json
# 特定セッションの合計コストだけを取り出す
npx ccusage@latest claude session --id <session-id> --json | jq '.totalCost'Claudeのセッションの--idには、JSONLのファイル名(拡張子.jsonlを除いたもの)を渡します。ccusage claude sessionの出力で、どのファイルがどのセッションかを確認できます。コスト列を出したくない画面共有やスクリーンショットでは、--no-costでコスト列を隠し、--compactで狭い表にできます。
ログの置き場所を変えている場合は、環境変数CLAUDE_CONFIG_DIRで指す先を教えます。既定ではccusageは~/.config/claudeと~/.claudeの両方を探します。カンマ区切りで複数のディレクトリも指定でき、別マシンから持ち出したログをまとめて集計するときにも使えます。
/usage・/costとccusageは何が違うか
/costは/usageの別名で、同じ画面を開きます。以降は/usageで統一し、ここまでの内容をClaude Code標準の機能と並べてまとめます。/usageの仕様は公式のコスト管理ページに沿っています。
| 観点 | /usage(標準) | ccusage |
|---|---|---|
| 集計の単位 | /usage(標準)現在のセッション(Session block)と、プランの按分(直近24時間/7日) | ccusage日・週・月・セッション・5時間ブロック |
| 過去の振り返り | /usage(標準)日付を指定して履歴を並べる用途ではない | ccusage--since / --untilで任意の期間 |
| データの出どころ | /usage(標準)ローカルのトークン数から、リスト価格で算出 | ccusageローカルのJSONL。costUSDかトークン数から算出 |
| プラン上限との関係 | /usage(標準)プラン使用量バーが上限の状況を示す | ccusageトークン数の集計のみ。上限そのものは分からない |
| 導入 | /usage(標準)組み込み | ccusagenpxで都度実行 |
/usageのSession blockの金額は、トークン数をリスト価格で掛けたローカルの試算値です。管理者がmanaged settingsでmodelPricing表を設定していれば、契約単価で計算され、Total cost行に「at your organization's configured rates」と注記が付きます。ccusageはその表を参照する旨の記載がなく、契約単価の組織では数字が合わない可能性があります。
公式の説明では、/usageのSession blockはAPI利用者向けで、ProやMaxのサブスクライバーでは使用量がサブスクリプションに含まれるため、セッションコストは請求の目安にならないとされています。ccusageの金額も、トークン数から出した試算である点は同じです。サブスクリプション利用者にとっての意味は「請求額」ではなく「API単価で換算したら大きさがどのくらいか」という物差しになります。請求の正は、公式がConsoleのUsageページとしているとおり、アカウント側の画面です。
数字がずれる典型パターン
/usageとccusageを並べたときにずれやすい理由は、次の4つに集約できます。
/usageのSession blockは/clearでリセットされるが、ccusageは同じ日のログをすべて合算する(v2.1.211より前の/usageは/clearをまたいで累積していた)- ccusageの
autoモードは記録済みのcostUSDを優先するため、calculateモードの数字と一致しない - 管理者設定の
modelPricingがあると/usageは契約単価になる - データ残量の差:ログが削除されていれば、ccusageには過去の日が出ない
プラン使用量バーとの突き合わせでは、ccusageのブロックと/usageの按分が同じ窓を見ているとは限りません。/usageの按分は直近24時間と7日の窓で、ccusageのブロックは最初のメッセージ起点の5時間窓です。両者の数字を揃える作業はせず、見たいことで使い分けるほうが実用的です。
ステータスラインに常時表示する
ccusageにはstatuslineコマンドがあり、Claude Codeのステータスライン用に使えます。README上では「Beta」と表記されています。ブロックのライブ監視が廃止された代わりの経路にあたります。
ccusage公式ドキュメントでは、~/.claude/settings.jsonのstatusLineにコマンドを書く形で設定します。npxを使う例は次のとおりです。
{
"statusLine": {
"type": "command",
"command": "npx -y ccusage statusline",
"padding": 0
}
}表示されるのは、現在のモデル、今のセッションのコスト、今日の累計、進行中の5時間ブロックのコストと残り時間、1時間あたりの消費ペース、コンテキスト使用量です。既定ではキャッシュ済みの料金データを使うオフラインモードで動き、最新の料金が必要なときだけ--no-offlineを付けます。--cost-source bothを付けると、Claude Codeの計算値とccusageの計算値を並べて表示するため、ずれの確認にも使えます。
標準のstatuslineでも、セッションコストは表示できます。設定項目やcost・prompt_cacheなどのフィールドはClaude Code statuslineの設定と表示項目の選び方にあります。常時表示したいのが「今のセッションの金額」だけなら標準機能で足ります。今日の累計や5時間ブロックの残り時間まで欲しいときに、ccusageの出番があります。
使い分けの目安
| やりたいこと | 向く手段 |
|---|---|
| 今のセッションがいくらか、キャッシュは効いているか | 向く手段/usage(標準) |
| プラン上限に対する残りを知る | 向く手段/usageのプラン使用量バー |
| 先月どの日が重かったか | 向く手段ccusage claude daily --since ... --until ... |
| どの会話が高かったか | 向く手段ccusage claude session |
| リポジトリ別のコスト | 向く手段ccusage claude daily --instances |
| 5時間窓ごとの消費ペース | 向く手段ccusage blocks --active |
| 組織の支出管理・上限設定 | 向く手段Claude ConsoleやTeams・Enterpriseの管理画面 |
/usageの読み方はClaude Codeの/usageコマンドで見る使用量の内訳、チーム単位で支出を可視化して抑える方法はClaude Codeのコスト管理が扱っています。ccusageは、その2つの隙間にある「個人のローカル履歴を日付で並べる」役割を担う道具です。
つまずきやすい点
- 全エージェントが混ざる:
ccusage dailyは検出した全ソースを統合する。Claude Codeだけならccusage claude dailyにする - 昔の記事のオプションが動かない:
blocks --liveはv18.0.0で削除済み。代わりにstatuslineを使う - 過去の日が空になる: Claude Code側が
cleanupPeriodDays(既定30日)で古いセッションを削除している。必要な月は--jsonで退避する - 日付がずれて見える: 日付のグルーピングはタイムゾーン依存。
--timezoneで揃える。ブロック境界はUTC基準で計算される - ログを別ディレクトリに置いている:
CLAUDE_CONFIG_DIRでccusageにも場所を伝える displayで合計が小さい:costUSDが無い行は$0.00になる。autoかcalculateで見直す- 新モデルの単価が反映されない:
calculateの単価は外部の価格データベース依存。反映が遅れる期間はccusage.jsonの設定で単価を上書きする方法がある(README上は「Custom Pricing Overrides」)
まとめ
ccusageは、Claude Codeのローカルログを日・月・セッション・5時間ブロックで集計し直す、読み取り専用のレポートツールです。npx ccusage@latest claude dailyで動き、--since/--untilで期間、--instancesでプロジェクト別、--jsonで保存まで1つの道具で完結します。
覚えておきたい点は3つです。金額はトークン数から出した試算で請求額ではないこと。--modeでコストの出し方が変わること。そしてローカルログの保存期間を超えた分は見られないことです。今のセッションと上限の状況は/usage、過去の振り返りはccusageと分けて使うと、数字がずれたときも原因を追えます。