Claude Usage Viewer
Claude Code の使用状況を VS Code のステータスバーに常時表示する拡張機能です。
v0.2 の芯は「取りに行かない」設計です。 5時間/週次の使用率は、Claude Code 本体が statusline 機能へ渡している公式計算値(/usage コマンドと同一ソース)を、ローカルの ~/.claude/statusline-state.json 経由で受け取ります。推定コスト・トークン数は ~/.claude/projects のログをローカル集計します。既定設定では、この拡張は認証情報(OAuthトークン等)に一切触れず、ネットワーク通信も一切行いません。
開発経緯のメモ: v0.1 では5h/週次を非公式API /api/oauth/usage から取得する設計でしたが、実機検証では誠実な独自User-Agentでの呼び出しが一貫してレート制限(429)となり、一度も表示できませんでした。v0.2 で「Anthropicへ取りに行く」のをやめ、「Claude Code がすでにローカルへ届けている公式値を受け止める」方式に転換したことで、この問題は前提ごと解消しています。
表示例(テキスト図)
通常時(ブリッジ設定済み・Claude Code 稼働中)
[ 推定$12.34 · 5h 19% · 7d 11% ]
警告・危険時(しきい値超過)
[ 推定$12.34 · 5h 78% · 7d 45% ] ← 背景が警告色(黄)
[ 推定$12.34 · 5h 94% · 7d 60% ] ← 背景が危険色(赤)
Claude Code をしばらく動かしていない時(最終受信時点の値を表示し続ける)
[ 推定$12.34 · 5h 19% · 7d 11%(42分前) ]
ブリッジ未設定時(③のみ表示+セットアップ誘導)
[ 推定$12.34 · 5h/7d 未受信 ]
ホバー時のツールチップ(内訳)
Claude Usage Viewer
| 項目 | 値 | 期間 |
|-------------------------------|-------------------|-----------|
| 推定コスト(JSONL集計・推定値) | $12.34 / 1.2M tok | 直近7日 |
公式値の最終受信: 3分前
| 項目 | 値 | リセット |
|-----------------|------|---------------------|
| 5時間ウィンドウ | 19% | 07/04 22:10 (あと2h13m) |
| 週次(全体) | 11% | 07/09 23:00 |
5h/週次はClaude Code本体が計算した公式値(statusline経由)です。
推定コストはローカルログからの概算で、実際の請求額と一致しない場合があります。
セットアップ(公式値の受信に必要・1回だけ)
5h/週次の公式値を受け取るには、Claude Code の statusline に「受信JSONをファイルへ書き出す」ブリッジを設定します。コマンドパレットから Claude Usage: Set Up Statusline Bridge を実行してください。
- statusline を使っていない場合: 確認ダイアログで同意すると、ブリッジスクリプトを
~/.claude/claude-usage-viewer-bridge.js に作成し、~/.claude/settings.json に statusLine 設定を追加します(既存の settings.json はバックアップを作成します)。CLI 側の statusline には簡潔な使用率ラインが表示されるようになります。
- すでに statusline を使っている場合: 既存設定は上書きしません。お使いのスクリプトに数行追記する手順書が開きます(表示への影響はありません)。
- セットアップ後、Claude Code を1ターン実行すると公式値が届き、ステータスバーに自動反映されます(state ファイルの更新は fs.watch で検知するため、ポーリング間隔を待ちません)。
ブリッジを設定しない場合でも、推定コスト表示(③)はそのまま動作します。
機能
- 推定コスト・トークン数(常時動作):
~/.claude/projects/**/*.jsonl のログをローカルで集計し、モデル別単価表からコストを推定します。認証情報を読み取らず、ネットワーク通信も行いません。
- 5時間ウィンドウ / 週次使用率(公式値): statusline ブリッジ経由で Claude Code 本体の計算値を表示します。しきい値(既定70%/90%)に応じて色分けします。Claude Code 非稼働中は最終受信時点の値を経過時間つきで表示します。
- コンテキスト使用率(オプトイン):
showContextPercentage を有効にすると現在セッションのコンテキスト使用率も表示します。
- クレジット(extra usage、オプトイン・既定OFF):
showCredit を有効にした場合のみ、非公式API /api/oauth/usage から追加使用額の取得を試みます(下記「非公式データ源について」参照)。
- ホバーツールチップ / クリックで詳細(QuickPick): 内訳表示と「今すぐ更新」「設定を開く」のショートカット。
- 劣化時も理由付きで表示: 未セットアップ・ファイル読取エラー等の状態を理由とともに表示し、クラッシュしません。どの系統が落ちても他の系統の表示は消えません。
対象プラン
- 推定コスト・トークン数はプランを問わず動作します(ローカルログのみを使うため)。
- 5時間/週次使用率は Claude Pro / Max などサブスクリプションプランが対象です(Claude Code が rate_limits を statusline へ渡すのはこれらのプランのみ)。APIキー従量課金では値が届かないため表示されません。
設定
| 設定キー |
既定値 |
説明 |
claudeUsageViewer.pollingIntervalSeconds |
300 |
ローカル集計と受信状態を確認する間隔(秒)。最小30秒。state ファイルの更新は fs.watch で即時反映されるため、通常は変更不要。 |
claudeUsageViewer.showFiveHour |
true |
5時間ウィンドウの使用率を表示する。 |
claudeUsageViewer.showWeekly |
true |
週次(7日)使用率を表示する。 |
claudeUsageViewer.showCost |
true |
ローカルJSONLログから推定したコスト/トークン数を表示する。 |
claudeUsageViewer.showCredit |
false |
(オプトイン)クレジット(extra usage)使用額を表示する。有効にした場合のみ非公式APIへの通信と .credentials.json の読み取りを行う。 |
claudeUsageViewer.showContextPercentage |
false |
(オプトイン)コンテキスト使用率を表示する(statuslineブリッジ経由)。 |
claudeUsageViewer.warningThreshold |
70 |
警告表示に切り替える使用率のしきい値(%)。 |
claudeUsageViewer.criticalThreshold |
90 |
危険表示に切り替える使用率のしきい値(%)。 |
claudeUsageViewer.statusBarAlignment |
right |
ステータスバー項目の表示位置(left/right)。 |
claudeUsageViewer.statuslineStatePathOverride |
"" |
statusline-state.json のパスを明示指定する。空なら CLAUDE_CONFIG_DIR または ~/.claude 配下を自動解決。 |
claudeUsageViewer.statuslineStaleMinutes |
15 |
公式値の最終受信がこの分数より古いと経過時間つき表示に切り替える。 |
claudeUsageViewer.credentialsPathOverride |
"" |
.credentials.json のパスを明示指定する。showCredit 有効時のみ使用される。 |
データ源の性質とリスク
- statusline(5h/週次・コンテキスト%): statusline は Claude Code の公式ドキュメントに記載された機能で、値は本体の
/usage と同一のサーバー計算値です。ただし stdin JSON の内部フォーマットは将来変更される可能性があり、その場合この拡張の①②表示が動作しなくなることがあります(③には影響しません)。ブリッジ(JSONのファイル書き出し)はこの拡張独自の仕組みです。
- ローカルログ(
~/.claude/projects/**/*.jsonl): Claude Code CLI が記録するセッションログです。推定コストはあくまで概算で、モデル別単価表はハードコードされており、実際の請求額と一致しない場合があります。
/api/oauth/usage(クレジット表示・オプトイン): Anthropicの公式ドキュメントに存在しない非公式APIです。開発時の実機検証では誠実なUser-Agentでの呼び出しが一貫して429(レート制限)となり、200レスポンスを一度も確認できていません。有効化しても取得できない場合が多いこと、Anthropicの一存で予告なく変更・廃止されうることをご了承ください。
トラブルシューティング
- 「5h/7d 未受信」と表示される: コマンド「Claude Usage: Set Up Statusline Bridge」を実行してブリッジを設定し、その後 Claude Code を1ターン実行してください。
- 「(N分前)」が付いたまま更新されない: Claude Code が稼働していない間、公式値は更新されません(仕様)。Claude Code を使い始めると自動的に最新化されます。
- 5h/7d の数字自体が出ない: お使いのプラン(APIキー従量課金等)では rate_limits が提供されていない可能性があります。推定コスト表示は引き続き利用できます。
- 推定コストが
$0.00 のまま: 直近7日以内に ~/.claude/projects にセッションログが記録されていない可能性があります。CLAUDE_CONFIG_DIR を設定している場合はそのパス配下を確認してください。
- Windows以外での動作: パス解決ロジックは3OS分岐で実装していますが、開発・動作確認はWindows環境のみで行っています。macOS/Linuxでの動作は未検証です。
プライバシー・セキュリティ
- 既定設定では、この拡張はネットワーク通信を一切行わず、認証情報(OAuthトークン等)にも一切触れません。 読むのはローカルの
statusline-state.json(使用率等の数値のみで、トークンは含まれません)とセッションログだけです。
showCredit を有効にした場合のみ、.credentials.json を読み取り(書き込みは行いません)、Anthropic の公式APIエンドポイントへのリクエストに使用します。トークンの値をログ・画面・エラーメッセージに出力することはありません。- セットアップコマンドによる
~/.claude/settings.json の変更は、必ず確認ダイアログでの同意後に、バックアップを作成してから行います。
既知の制限
- 週次(Opus)の個別表示はできません(statusline JSON に含まれないため)。
- 公式値の更新は Claude Code の稼働中のみです。
- バーンレート予測(残り時間の推定)は今バージョンでは未実装です(公式値の履歴が高頻度で得られるようになったため、次バージョン以降の検討課題)。
- macOS/Linux での動作は未検証です。
ライセンス
MIT License。詳細はパッケージ内の LICENSE ファイルを参照してください。
