Claude Usage

claudeusage

Claude サブスクリプションが実際に元を取れているかを測定します。ローカルログから測定し、アップロードも Git 連携も不要です。

ステータス：完了（2026年10月）。 個人的な調査プロジェクトです。動作しており、公開を続けていますが、今後開発される予定はなく、イシューへの返信がない場合があります。以下の測定値は、約5週間（2026-09-01 → 10-08）にわたる1つのアカウントのデータに基づいています。

한국어 문서: README.ko.md — 韓国語版は作業ノートで、すべての測定値と、ここに至るまでに犯した間違いをまとめています。

なぜこのツールを作ったのか

サブスクリプションではトークンごとに料金を払わないため、うまく使えているかどうかを教えてくれるものがありません。個人向けツールの多くは、使用量の多さを数えます。それは適切な指標ではありません。無駄にトークンを消費しても高得点になってしまいます。Meta はそのような社内ランキングを運用していましたが、停止しました。人々が順位を上げるために AI をアイドル状態にし始めたためです。無駄を調べる無料のプロファイラーはいくつかありますが、API のドル建て料金で計算します。一方、サブスクリプションで尽きるのは利用制限のゲージであり、トークンの重み付けは料金とは大きく異なります（後述）。

品質を測定するツールもありますが、どれもチーム向けに作られています。Git リポジトリ、PR、イシュートラッカーが必要です。そのため、未解決の課題が残っています。

	チーム向けツール	claudeusage
測定対象	リードがチームを測定	自分自身を測定
必要なもの	Git リポジトリ、PR、トラッカー	ローカルログディレクトリ1つ
測定内容	チーム投資に対するリターン	サブスクリプションが元を取れているか
料金	SaaS またはセルフホスト可能	無料、ローカルで実行

Git ベースのツールは git blame でコードを追跡するため、コミットしていないものはすべて見えません。このツールは編集履歴そのものを再構築するので、実験や、コミット前に書き直したコードもカウントされます。

測定内容

残った行。 すべての編集を時系列順に反映するため、セッションの最後に残っていたものだけがカウントされます。3ターン後に書き直したコードは自動的に除外されます。アイドル状態にしてスコアを操作することはできません。

金額で見た無駄。 手戻り、失敗、却下を合わせると、ここでは4.1％です。会話が長くなったことで消費された金額は、**12.3％**です。どちらも API のドル建て金額です。新しい会話を始めることで実際に利用制限を節約できるかどうかは、証明されていません。新しい会話ではコンテキストを読み直すコストがかかるためです。そのため、12.3％は目安として捉え、確約とは考えないでください。

レート制限で実際に消費されるもの。 実際の制約はドルではなく、利用制限のゲージです。キャッシュ読み取りはコストの大部分を占めますが、利用制限に対する重みは新規入力の約1/70です。金額の節約と利用制限の節約は、別のスキルです。

チャットが消費した分。 利用制限はアカウント全体に適用されるため、claude.ai のチャットとモバイルアプリも同じゲージを消費しますが、ローカルには記録が残りません。ログだけを使うツールは、どれも過少に計上します。このツールは、実際のゲージの変化からログで説明できる分を差し引き、その推定値を Anthropic が返す製品別内訳と照合します。

1つのアカウントのデータから分かったこと

約52,000件のステータス行サンプルと、33,000件のログ記録されたリクエストから測定しました。各倍率は、何を基準にした値かを明記しています。

• 利用制限に対するキャッシュ読み取りの重みは、新規入力の約1/70（トークンごとに、107件の5時間ウィンドウで適合）。全トークンの97％を占め、金額コストの大部分を占めますが、利用制限の消費量は出力、新規入力、キャッシュ読み取りでほぼ同じ割合になります。金額ベースの無駄の報告では、キャッシュ読み取りが過大評価されます。
• 週次制限の変更はゲージにのみ現れます。 週次の増加 ÷ 5時間の増加は、0.099（40ウィンドウ、09-01→13）から0.125（41ウィンドウ、09-15→10-02）に変化しました：1.26倍です。Anthropic が発表した変更（ボーナス +50％ → +25％）からは1.20倍と予測されます。これは公表された変更を確認するものにすぎず、1つのアカウントでの誤差は約±3％です。
• 出力トークンあたりのモデルの重み。Opus 5 = 1： Fable 5.1 ≈ 3.8倍、Opus 4.8 ≈ 1.7倍（条件の整ったウィンドウが少ないため、傾向は確かですが、正確な値ではありません）。
• Claude Code 以外のチャットは利用制限の約10％を消費しており、 Anthropic が返す製品別内訳の8〜9％と一致しています。

インストール

Python 3.9 以降（標準ライブラリのみで、依存関係はありません）と、ライブ制限ツールを使用する場合は macOS が必要です。

git clone https://github.com/syk8015/claudeusage && cd claudeusage
./install.sh                   # package + skill + MCP server (user scope)
claude mcp list                # claudeusage … ✔ Connected

install.sh はパッケージをインストールし（uv、pipx、pip、専用の venv の順に試します。最近の Python ではシステムへのインストールがブロックされるためです）、Claude Code のスキルを ~/.claude/skills/ に配置し、MCP サーバーを登録します。./install.sh --uninstall で元に戻せます。

これにより、claudeusage コマンドと claudeusage-mcp サーバーを使用できます。PyPI でのリリースはありません。クローンからインストールしてください。

制限ツールを使うためのもう 1 つの手順

Claude Code は制限ゲージを表示しますが、その値は保存しません。claudeusage limit と claudeusage chat にはその履歴が必要なので、ステータスラインにコレクターを設定する必要があります。~/.claude/settings.json に次の内容を追加してください。

"statusLine": {
  "type": "command",
  "command": "claudeusage statusline --print"
}

すでにお好みのステータスラインを使っていますか？--print を削除してパイプでつなげば、コレクターが JSON をそのまま渡します。

"command": "claudeusage statusline | bash ~/.claude/my-statusline.sh"

設定は自動で編集されません。ステータスラインの設定はご自身で管理してください。

コレクターなしで、claudeusage value と claudeusage usage はすぐに使えます。制限の分析が役立つようになるまで、数日分のサンプルが必要です。

サンプルは ~/.claudeusage/ に保存されます（CLAUDEUSAGE_DATA で変更できます）。クローンから実行した場合は、引き続きリポジトリ独自の data/ ディレクトリが使用されるため、既存の履歴が取り残されることはありません。

Claude から使う

自然な言葉で質問してください。「料金に見合う価値はありますか？」「なぜこんなに早く制限が減るのですか？」「チャットで制限をどれくらい使いましたか？」などと尋ねると、スキルが適切なツールを選びます。

MCP ツール	回答する内容
subscription_value	残った行、無駄、アクティビティ別のコスト
limit_breakdown	5 時間および週間の制限に影響する要因
chat_share	チャットで制限をどれくらい使ったか
current_limits	現在の制限と、製品別の内訳

シェルから使う

claudeusage value --all              # all projects
claudeusage value --project PATH --waste
claudeusage limit                    # limit burn per 5-hour window
claudeusage limit --fit              # fit: what the gauge weighs
claudeusage chat                     # chat's share, weekly
claudeusage usage                    # live limits + product breakdown
claudeusage check                    # both consistency checkers

出力はデフォルトで英語です。CLAUDEUSAGE_LANG=ko にすると韓国語に切り替わります。

チャット使用量の推定方法

3 つの情報源は、それぞれ異なる状況で把握できない情報があるため、組み合わせて使用します。

情報源	得られる情報	把握できない場合
ステータスラインのサンプル（claudeusage statusline）	リセット時刻付きのゲージ値	Claude Code が実行されていない
Claude デスクトップアプリの履歴	15 分ごとのゲージ値	アプリが実行されていない
OAuth 使用量エンドポイント	製品別の実際の使用量（Claude Code／チャット／Cowork）	現在の週間ウィンドウのみ

推定値は差し引きで算出します。chat = ゲージの増加量 − ローカルログで説明できる量。「説明できる」量の算出には、claudeusage limit で調整したモデル別の重みを使います。この重みは、ログに記録されていない使用量の疑いがないウィンドウだけを対象に調整されます。そうしないと、チャットの使用量によって重みが膨らみ、推定器が自身の使用量を把握できなくなるためです。

実データで実行して初めて見つかった、修正が必要な点が 2 つありました。

1. 観測が不完全なウィンドウは差し引きに偏りを生じさせます。 ウィンドウの一部しかゲージを監視していないと、増加量は低く、割り当てられるコストは高く算出されます。リセット時刻が判明していて、ゼロから監視できたウィンドウのみを集計します（ここでは 107 件中 55 件）。
2. ログ由来のコストは 6～9％低く算出されます。バックグラウンドの呼び出しがログに残らないためです。そのままにしておくと、この差が架空のチャット使用量になります。各ウィンドウをステータスラインの合計値に合わせて補正します。

claudeusage check は、実際のウィンドウでチャット使用量を手動確認した結果を含む、15 個の不変条件を検証します。

精度について、率直に

• 製品ごとの内訳が実際の値ですが、収集できたのはその週次ウィンドウが2つだけです。推定器を「検証済み」と呼ぶには、さらにデータが必要です。
• Opus 5.5 のトークンごとの適合は不安定です。40個のウィンドウでは出力トークンの重みがゼロになり、これは正しくありません。入力同士に相関があるため、トークンごとの数値より、ドルごとの数値のほうが安定しています。
• Claude Code はデフォルトで30日後に会話ログを削除します（cleanupPeriodDays）。それより古いゲージサンプルでは必要なリクエストデータが失われるため、上限の適合に使われるのは常に直近1か月分だけです。
• 使用頻度が低いモデルの重みは、データがクリーンな5～7個のウィンドウから算出されています。傾向は確かですが、正確な倍率はまだ変動します。
• 上限ゲージは整数です。変化点は大まかなため、約1,200個の変化点の平均値を回答として示します。
• claudeusage usage は Claude Code の認証情報を macOS キーチェーンから読み取り、api.anthropic.com にのみ送信します。認証情報を表示したり保存したりすることはありません。記録する情報は許可リストに含まれるもののみです。タイムスタンプ、上限の種類、モデル名、割合、リセット時刻、製品ごとの使用割合です。

対象範囲

Claude のみです。「コーディングとチャットを統合する」当初の計画では ChatGPT と Gemini のエクスポートも統合する予定でしたが、意図的に取りやめました。ここにあるものはすべて、1つの Claude アカウントとそのレート制限を基準に構築されています。

レジストリ

公式 MCP レジストリには io.github.syk8015/claudeusage として登録されています。

Glama にも登録されています。

ライセンス

MIT