ccusage 使い方｜Claude Codeのトークン消費をCLIで可視化（★13,000超）完全ガイド

結論：ccusage は、Claude Codeがローカルに残す会話ログ（JSONL）を解析し、日次・週次・月次・セッション・5時間ブロック単位でトークン消費量とコストを可視化するOSSのCLIツールです。追加のAPIキーやログインは不要で、npx ccusage@latest を叩くだけで当日の使用量が出ます。GitHubスターは13,000超（2026年4月時点）、Claude Codeユーザーの実質的な標準ツールとして定着しています。

この記事でわかること

ccusageの概要・ライセンス・料金（無料）
最短1コマンドで使い始めるインストール手順
daily / weekly / monthly / session / blocks / statusline の使い方
5時間課金ブロックの読み方と、いま投げてよいトークン量の判断方法
Claude CodeのstatusLineへの常時表示組み込み手順
複数アカウント／チームでの集計方法（CLAUDE_CONFIG_DIR）
MCPサーバ連携（@ccusage/mcp）とCodex CLIなど派生パッケージ
よくあるトラブルとFAQ

誰向けの記事か

Claude Code（Pro / Max5 / Max20）を日常的に使っていて、5時間ブロックを枯らしてしまう方
Claude APIの従量課金額をざっくり把握したい方
チームでClaude Codeを運用していて使用量を集計・共有したい方

ccusageとは？13,000スター超のローカル可視化CLI

ccusageは、Claude Codeや一部のCodex系CLIがローカルに残すJSONL形式のログを解析し、トークン使用量とコストをターミナルに表形式で出力するオープンソースのCLIです。開発者は@ryoppippi氏（個人OSSメンテナ）、ライセンスはMIT、配布はnpm経由です。

項目	内容
名称	ccusage
開発者	@ryoppippi
ライセンス	MIT（OSS）
公式サイト	https://ccusage.com/
GitHub	https://github.com/ryoppippi/ccusage
GitHubスター	13,300+（2026-04時点）
最新バージョン	v18.0.11（2026-04-19）
実装言語	TypeScript（Bun前提のモノレポ構成）
料金	無料
実行形態	ローカル／外部サーバへのデータ送信なし

一般的に「Claude Codeの使用量を確認するツール」は複数ありますが、ccusageは「ログをそのまま読む／追加の認証なし／CLIで即出せる」の3点で軽量さが際立ち、Claude Code v1.0.30以降のデータディレクトリ変更にも自動追従します。

なぜ13,000スター超の定番ツールになったのか

短く言うと、Claude Code定額プラン（Pro / Max5 / Max20）の「5時間ブロック上限」と「いま何トークン使ったか」を、もっとも軽い手順で把握できるからです。主な評価ポイントは次の3つに集約されます。

1コマンドで動く: npx ccusage@latest だけで日次集計が出る。事前設定がほぼ不要。
ローカル解析: API呼び出しや外部サーバ送信がなく、会話本文はccusage側に出ない。価格データの取得通信も CCUSAGE_OFFLINE で遮断できる。
Claude Codeの課金単位に合わせた集計: Claude Codeは「メッセージ単位」ではなく 5時間ブロックで使用量を管理する仕様で、ccusageの blocks はその単位に揃えて表示する。

現時点では、個人開発者だけでなくチームでのClaude Code運用コスト可視化にも広く使われています。

ccusageの料金・ライセンス・安全性

ccusage本体は無料（MITライセンス）です。 APIキーの登録や会員登録は不要で、ローカルに保存されているClaude CodeのJSONLログを読み取るだけで動作します。

項目	内容
ツール本体	無料
ライセンス	MIT
認証情報	不要（APIキー・ログイン不要）
対象ログ	`~/.config/claude/projects/` または `~/.claude/projects/` 配下のJSONL
外部通信	価格データ取得のため `raw.githubusercontent.com` へHTTPS接続する場合あり。`CCUSAGE_OFFLINE` または `--offline` で停止可能
対象プラン	Claude Code 定額プラン（Pro / Max5 / Max20）／ Claude API 従量課金

公式ではccusageはAnthropicの公式ツールではなく、第三者OSSとして提供されている点に注意してください。金額は「ログに記録されたトークン数 × モデル単価」で推定される値であり、Anthropicの請求額と完全一致を保証するものではありません（とはいえ実務ではほぼ一致します）。

インストール方法

推奨は都度実行の npx ccusage@latest です。 常駐しないCLIなので、グローバルインストールよりもバージョン固定リスクが少なく、価格データも最新が適用されます。

最速で試す（npx / bunx / pnpm dlx）

# npx（Node.js 20+）
npx ccusage@latest

# Bun
bunx ccusage

# pnpm
pnpm dlx ccusage

初回実行時にパッケージがキャッシュされ、2回目以降は高速に起動します。

Denoで実行する場合

deno run -E -R=$HOME/.claude/projects/ -S=homedir \
  -N='raw.githubusercontent.com:443' npm:ccusage@latest

Denoは明示的な権限指定が必要なため、環境変数・ファイル・ネットワーク権限を上のように限定して与えます。

グローバルインストール

頻繁に叩くなら次のいずれか。

npm i -g ccusage
bun i -g ccusage
pnpm add -g ccusage
yarn global add ccusage

ランタイム要件

Node.js 20以上
Bun 1.2以上
Deno 2.0以上

「Homebrew版は？」という質問が多いですが、公式ドキュメント上の配布経路はnpm / bun / pnpm / yarn / Denoです。非公式ラッパーに依存する場合は @latest が遅れる可能性があるため、公式経路を推奨します。

最速で試す手順：`npx ccusage@latest`

まず下のコマンドを叩いてください。それだけで「今日までの日別トークン使用量とコスト」が表形式で表示されます。

npx ccusage@latest

ccusage は引数なしで呼ぶと daily サブコマンドと同じ動作をします。表示される主なカラムは以下です。

カラム	意味
Date	日付
Input / Output / Cache Create / Cache Read	モデルに投げた／モデルから返ってきた／キャッシュ生成／キャッシュ読込の各トークン数
Total Tokens	その日の合計
Cost (USD)	推定コスト

表示されなかった場合は、Claude Codeを1回でも使ってJSONLログが生成されているかを確認してください（詳細はトラブルシューティング節）。

基本コマンド一覧

ccusageは集計粒度ごとにサブコマンドが分かれた設計です。v18系で weekly と statusline が追加されました。

コマンド	用途
`ccusage` / `ccusage daily`	日次トークン量・コスト
`ccusage weekly`	週次レポート（v18で追加）
`ccusage monthly`	月次集計
`ccusage session`	Claudeセッション（会話）単位
`ccusage blocks`	Claude Codeの5時間課金ブロック単位
`ccusage statusline`	statusLine用の1行要約（ベータ）

以下、それぞれの代表的な使い方を示します。

daily：日次レポート

# 直近の日次集計（既定）
npx ccusage@latest daily

# 期間指定
npx ccusage@latest daily --since 20260401 --until 20260430

# モデル別内訳を表示
npx ccusage@latest daily --breakdown

# JSONで出力（自動集計に使いやすい）
npx ccusage@latest daily --json

主なオプション:

--since YYYYMMDD / --until YYYYMMDD : 期間フィルタ
--order asc | desc : 並び順
--mode auto | calculate | display : コスト算出方針
- auto（既定）: 事前計算値を優先し、なければ都度算出
- calculate: 常にトークン数から再計算
- display: 事前計算値のみ表示
--breakdown : モデル別内訳
--compact : 表示を圧縮
--timezone <TZ> / --locale <lang>
--json : JSON出力

weekly：週次レポート（v18新規）

npx ccusage@latest weekly

週単位で使用トークンと推定コストを丸めて表示します。Max5やMax20のプラン運用レビューに便利です。

monthly：月次集計

npx ccusage@latest monthly --breakdown

月次＋モデル別にすると、APIに投げた重めの処理がどのモデルだったかまで一望できます。

session：セッション単位

npx ccusage@latest session

「1つの会話（セッション）」単位で使用量を積算します。長く引っ張った会話ほどキャッシュと合わせて伸びるので、どの会話がコストに効いているかを可視化できます。

blocks：5時間課金ブロック

# 直近のブロック
npx ccusage@latest blocks

# 進行中ブロックのみ（バーンレート・予測を表示）
npx ccusage@latest blocks --active

# 直近3日のブロック
npx ccusage@latest blocks --recent

# トークン上限を意識したい（数値 or "max"）
npx ccusage@latest blocks --token-limit max

詳細は次節で扱います。

statusline：1行要約（ベータ）

npx ccusage@latest statusline

単体実行ではClaude Code側のstdinを模した入力が必要なため、基本はClaude Codeの設定から呼び出されるコマンドとして使います（後述）。

5時間ブロックの読み方：`blocks --active`でバーンレート

Claude Code定額プランは「最初のメッセージから5時間」を1ブロックとして課金するローリングウィンドウ方式です。 ccusageの blocks はそのブロックに揃えて集計し、--active で進行中ブロックだけを取り出せます。

npx ccusage@latest blocks --active

--active では以下のような情報が出ます。

現在ブロックの開始時刻と残り時間
現在ブロックの使用トークンと推定コスト
バーンレート（分あたりトークン／時間あたりコスト）
ブロック終了時の予測トークンとコスト

現時点では、5時間ブロック上限の具体的な数値（例：Pro / Max5 / Max20 の閾値）はAnthropic公式の料金ページでの確認を推奨します。ccusage自体はプラン種別を判定しないため、--token-limit で閾値を渡すと「このままのペースで到達しそうか」を直感的に見積もれます。

# 10万トークンを上限と仮定して、到達予測を見たい
npx ccusage@latest blocks --active --token-limit 100000

# プラン上限のつもりで max（公式ログ上の最大値）を渡す
npx ccusage@latest blocks --active --token-limit max

読み方の実務Tips

バーンレートが通常より高いときは、大量のキャッシュ生成を伴うタスク（巨大なコードベースの読み込みなど）が入っている可能性が高い。
ブロック予測が閾値を超えそうなら、ブロック終端まで待つか、タスクを分割するかの判断材料になる。
--active はUTC基準で一貫しているため、タイムゾーンをまたぐチームでも同じ枠で議論できる。

statusLineに常時表示する：`ccusage statusline`

Claude CodeのstatusLine機能に ccusage statusline を接続すると、エディタ下部に「モデル／セッション／本日／ブロック／残り時間／バーンレート」が常時表示されます。

表示例:

🤖 Opus | 💰 $0.23 session / $1.23 today / $0.45 block (2h 45m left) | 🔥 $0.12/hr

設定方法

~/.claude/settings.json または ~/.config/claude/settings.json に次のように追記します（Bunを使う例）。

{
  "statusLine": {
    "type": "command",
    "command": "bun x ccusage statusline",
    "padding": 0
  }
}

npxを使う場合は "command": "npx ccusage@latest statusline" です。

便利なオプション

--no-offline : 価格データを常に最新取得
--visual-burn-rate emoji : バーンレートを絵文字でビジュアライズ
--cost-source auto | ccusage | cc | both : コストソースを切替
--context-low-threshold / --context-medium-threshold : コンテキスト使用率の色分け閾値

現時点でstatuslineはベータです。仕様追加・変更があり得るため、長期運用する際は@latest で呼び出すことを推奨します。

複数アカウント／チーム集計：`CLAUDE_CONFIG_DIR`

複数アカウントを使い分けている、あるいはチーム全員のログをまとめたい場合は、環境変数 CLAUDE_CONFIG_DIR にディレクトリをカンマ区切りで列挙します。

# 個人とワーク用アカウントを合算
export CLAUDE_CONFIG_DIR="$HOME/.claude,$HOME/work/.claude"
npx ccusage@latest monthly --breakdown

指定優先順は CLI引数 > 環境変数 > 設定ファイル > 既定値。CIなどでチーム集計ジョブを回す場合は、メンバー各自の ~/.claude/projects/ をまとめた場所をマウントし、CLAUDE_CONFIG_DIR で一括指定するのが定石です。

プロジェクト別にグルーピング

# プロジェクトごとに行を分ける
npx ccusage@latest daily --instances

# 特定プロジェクトだけ
npx ccusage@latest daily --project my-product

--instances（エイリアス -i）と --project <name>（-p）を組み合わせることで、プロジェクト横断の使用量内訳が出せます。

データディレクトリの場所（v1.0.30以降の注意点）

Claude Code v1.0.30 以降、データディレクトリが ~/.claude/projects/ から ~/.config/claude/projects/ に移動しました。 ccusageは両方を自動検出しますが、古い手順でバックアップを取っていると「昔のセッションは出るけど最新が出ない」といった挙動が起こり得ます。

バージョン	既定のデータディレクトリ
Claude Code v1.0.30 以降	`~/.config/claude/projects/`
Claude Code v1.0.29 以前	`~/.claude/projects/`

新旧どちらか片方にしかログが無い場合でも、ccusageは両方を見に行きます。明示指定したい場合は CLAUDE_CONFIG_DIR を使ってください。

MCPサーバ連携：`@ccusage/mcp`

ccusageはMCP（Model Context Protocol）サーバとしても提供されています。 本体をスリムに保つため、MCP機能は @ccusage/mcp という別パッケージに切り出されています。Claude Desktopなどから「ccusageに今月の使用量を聞く」といった使い方ができます。

起動

# stdio（Claude Desktopなどが直接spawn）
bunx @ccusage/mcp@latest

# HTTPストリーム
bunx @ccusage/mcp@latest --type http --port 8080

提供される主なツール: daily / monthly / session / blocks

Claude Desktop側の設定例

{
  "mcpServers": {
    "ccusage": {
      "command": "bunx",
      "args": ["@ccusage/mcp@latest"],
      "env": {}
    }
  }
}

MCPの基本は別記事にまとめています。

Codex / OpenCode用の派生パッケージ

Claude Code以外のCLIを使っている場合も、ccusageファミリーに対応パッケージがあります。

パッケージ	対象
`ccusage`（本体）	Claude Code
`@ccusage/codex`	OpenAI Codex CLI
`@ccusage/opencode`	OpenCode
`@ccusage/pi` / `@ccusage/amp`	その他CLI向け

オフラインモードの価格データはClaudeモデルのみが対象のため、Codex等を可視化する場合は対応パッケージを使い、必要に応じてオンライン接続を許可してください。

環境変数まとめ

変数	用途
`CLAUDE_CONFIG_DIR`	Claude Codeのデータディレクトリを明示。カンマ区切りで複数指定可
`CCUSAGE_OFFLINE`	値を設定するとオフラインモード強制。価格データ取得通信を止める
`LOG_LEVEL`	`0`（Silent）〜`5`（Trace）でログ詳細度を調整
`NO_COLOR` / `FORCE_COLOR`	カラー出力の制御

オフライン運用は、社内ネットワークが外向きHTTPSを絞っているケースや、監査上ccusageの通信を一切止めたいケースで重要です。

# 完全オフライン運用
export CCUSAGE_OFFLINE=1
npx ccusage@latest daily

セキュリティ観点での注意点

結論から言うと、ccusageがネットに出す情報は「どのモデルの単価を参照したか」だけで、会話本文やAPIキーは送信されません。 それでも実務で導入する際は次の4点を押さえておくと安心です。

ローカルのみを解析する: ~/.config/claude/projects/ 配下のJSONLを読み取るだけ。ツールがAnthropicに問い合わせる経路は持たない。
価格データのみ外部取得: raw.githubusercontent.com へHTTPS接続する場合がある。CCUSAGE_OFFLINE=1 または --offline / -O で遮断可。
チーム集計時のログ共有: ログにはプロジェクト名・メッセージ時刻・トークン数などが含まれる。プライバシー観点で共有範囲は事前合意すること。
@latest で実行: 価格表の更新・バグ修正が取り込まれる。キャッシュバージョンを長期間使い続けると推定コストが実際とずれることがある。

こんな方におすすめ

Claude Code定額プラン（Pro / Max5 / Max20）を使っていて、5時間ブロックを頻繁に枯らす方
- blocks --active でバーンレートを見ながらタスクを分割できる
Claude APIの従量課金を追加で使っていて、月額の目安を知りたい方
- monthly --breakdown でモデル別内訳まで出せる
エディタ下部にコスト情報を常時表示したい方
- statusline で「現ブロック残り時間＋推定コスト」を見ながら作業できる
チーム全員のClaude Code使用量を集計したい方
- CLAUDE_CONFIG_DIR で複数ディレクトリを合算
Claude Desktopから自然言語で使用量を聞きたい方
- @ccusage/mcp で会話中に「今月の消費は？」と聞ける

トラブルシューティング

「叩いたけどデータが何も出ない」系の問題はほぼ3パターンに集約されます。

1. データディレクトリが見つからない

Claude Code v1.0.30以降は ~/.config/claude/projects/ がデフォルトです。古い場所しか使っていない場合は明示指定してください。

CLAUDE_CONFIG_DIR="$HOME/.claude" npx ccusage@latest daily

両方に履歴があるのにどちらかしか出ない場合は、カンマ区切りで両方渡します。

CLAUDE_CONFIG_DIR="$HOME/.claude,$HOME/.config/claude" npx ccusage@latest daily

2. `blocks --live` が動かない

v18.0.0 で --live（ライブダッシュボード）は削除されました。 後継は statusline コマンドで、Claude CodeのstatusLineに組み込むのが標準です。古い記事に従って --live を探している場合は、statusline 側を確認してください。

3. 価格が出ない／ずれる

--offline / CCUSAGE_OFFLINE=1 を付けていないか確認
古いグローバルインストール版を使っていないか確認（npm ls -g ccusage）
解消しなければ npx ccusage@latest で都度最新を叩く

4. Node.jsのバージョンエラー

Node.js 20以上が必要です。古い環境では n/nvm/volta などでアップデートするか、Bun経由（bunx ccusage）で迂回してください。

FAQ

Q1. ccusageにAPIキーの登録は必要ですか？

不要です。 ローカルに保存されたClaude CodeのJSONLログを読むだけで動作します。Anthropic APIへのアクセス権限もccusage側では要求されません。

Q2. 会話の内容はどこかに送信されますか？

ccusageから外部に送信されるのは、参照したモデルの単価情報のリクエストのみです。 会話本文・APIキー・トークン内訳などが外部に出る設計ではありません。外向き通信を止めたい場合は CCUSAGE_OFFLINE=1 または --offline を使ってください。

Q3. 金額はAnthropicの請求額と一致しますか？

ccusageは「ログに記録されたトークン数 × モデル単価」で推定しているため、実務ではほぼ一致しますが、小数点レベルの差や、Anthropic側の割引・無料枠の計上タイミングで差が出ることがあります。請求額そのものを確定するにはAnthropic管理画面を参照してください。

Q4. statusLineはClaude Code Max20でも使えますか？

使えます。 statusLineはプランとは独立したClaude Codeの機能で、ccusageの statusline はログから推定コストを出すだけなので、どのプランでも動作します。ただしベータ機能のため仕様変更は起こり得ます。

Q5. `--live` が動かないのですが？

v18.0.0 以降で削除されました。 後継は statusline コマンドです。古いドキュメントや記事に沿って --live を使おうとしている場合は、Claude Code設定の statusLine に ccusage statusline を組み込む運用に切り替えてください。

Q6. Codex CLIの使用量も見られますか？

はい、その場合は @ccusage/codex を使います。 ccusage本体は主にClaude Code向けで、Codex CLIやOpenCodeには派生パッケージが用意されています。

Q7. MCPから使うと何が便利ですか？

Claude Desktop等の会話中に「今月の使用量は？」と聞くだけでccusageがツール呼び出しで答えてくれるため、いちいちターミナルに戻らなくて済みます。個別のサブコマンド（daily / monthly / session / blocks）がMCPツールとして提供されます。

Q8. チーム全員の使用量をまとめるには？

各メンバーの ~/.claude（または ~/.config/claude）配下をマウント・集約し、CLAUDE_CONFIG_DIR にカンマ区切りで列挙します。 CIでの定期集計に使うなら、集計結果を --json で吐かせて別の可視化基盤に流すのが実務では扱いやすいです。

Q9. Homebrewで入りますか？

公式のインストール経路はnpm / bun / pnpm / yarn / Denoです。 非公式ラッパーに頼るとバージョン追従が遅れる可能性があるため、npx ccusage@latest か公式パッケージマネージャを使うことを推奨します。

Q10. セッションを削除したり制限をかけたりできますか？

ccusageは可視化専用で、管理・削除・制限機能は持ちません。 セッションのクローズやログ削除はClaude Code側の操作で行ってください。

まとめ

ccusageは、Claude Codeの「いま何トークン使ったか／あと何トークン投げられそうか」を、インストール数秒・コマンド1行で可視化できるOSSのCLIです。 2026年4月時点でv18.0.11、GitHubスターは13,000を超え、Claude Codeユーザーの実質的な標準ツールとして定着しています。

本記事のポイントをまとめると次の通りです。

まずは npx ccusage@latest を叩く。引数なしで日次集計が出る
5時間ブロック上限は blocks --active でバーンレートと終了予測を見る
常時監視したいなら statusline をClaude Codeの settings.json に組み込む
複数アカウント／チームは CLAUDE_CONFIG_DIR をカンマ区切りで
会話中にコスト質問をしたいなら @ccusage/mcp を入れる
セキュリティが厳しい環境では CCUSAGE_OFFLINE=1 でオフライン運用

Claude Codeの料金を意識しながら開発するなら、ccusageは「まず最初に入れるコスト可視化ツール」として十分な選択肢です。本文の手順に沿って、今日の使用量から試してみてください。

この記事のポイント