claude-quota: macOS メニューバーで Claude Code の使用量を表示するゲージ

概要

claude-quota は Claude Code の使用クオータを追跡するために設計された macOS メニューバー ユーティリティです。SwiftBar プラグインを利用して、5 時間ウィンドウの利用状況と週次上限を、1 つまたは複数の Claude アカウントに対して macOS メニューバーに直接視覚的ゲージとして表示します。

主な機能と視覚的インジケータ

このツールは、色分けされたバーとカウントダウンタイマーを通じて、クオータの状態に対する即時の視覚的フィードバックを提供します。

  • 5 時間ウィンドウの利用状況: メニューバーは各アカウントごとにゲージを表示します。使用率に応じて色が変わります：低使用率は緑、$\ge 70%$ はオレンジ、$\ge 90%$ は赤。
  • リセットカウントダウン: 5 時間ウィンドウが完全に使い切られると、ゲージはカウントダウンタイマー（例: 4:28）に置き換わり、クオータがリセットされるまでの残り時間を示します。
  • 週次上限アラート: 週次上限に達すると、バーは黒くなり、週次リセットまでのカウントダウン（例: 2D）を表示します。これにより 5 時間ウィンドウの状態は上書きされます。
  • 詳細ドロップダウン: メニューバーのゲージをクリックすると、すべてのアカウントの包括的な詳細が含まれるドロップダウンが開きます。5 時間ウィンドウと週次ウィンドウ、モデル別ウィンドウ（報告されている場合）、余分な使用クレジット、特定のリセット時間などが含まれます。
  • 更新頻度: プラグインは自動で 5 分ごとに更新され、ドロップダウン内に手動の "Refresh now" オプションがあります。

技術的実装

claude-quota は macOS キーチェーンから Claude Code の OAuth トークンを読み取り専用で取得して動作します。その後、Claude Code の /usage 画面で使用されている内部の非公開使用エンドポイントに問い合わせます。

このツールはトークンを更新したり書き換えたりしないため、ユーザーをアカウントからログアウトさせることはできません。著者は、このエンドポイントが非公開であるため、Claude Code の将来的な変更に伴いプラグインの更新が必要になる可能性があると指摘しています。

インストールと設定

インストール

ユーザーは curl スクリプトまたはリポジトリのクローンでツールをインストールできます。

Quick Install:

curl -fsSL https://raw.githubusercontent.com/grzegorz-raczek-unit8/claude-quota/main/install.sh | bash

Manual Install:

git clone https://github.com/grzegorz-raczek-unit8/claude-quota.git
cd claude-quota
./install.sh

どちらのインストール方法も、Homebrew 経由で SwiftBar がまだインストールされていない場合は自動的にセットアップします。ユーザーは最初の更新時に macOS キーチェーンの権限ダイアログが表示されたら「Always Allow」を選択する必要があります。

アカウント管理

デフォルトでは、プラグインは ~/.claude と ~/.claude-* の設定ディレクトリをスキャンし、対応するキーチェーンエントリがあるアカウントを自動検出します。

  • ラベリング: 単一のアカウントはラベルなしで表示されます。複数のアカウントはディレクトリのサフィックスでラベル付けされます（例: ~/.claude-work は W になる）。
  • カスタマイズ: ユーザーは ~/.config/claude-quota/accounts ファイルを作成し、1 行に path [label] の形式で記述することでアカウントを固定または名前変更できます。
  • 表示/非表示: アカウントは ~/.config/claude-quota/hidden ファイルやドロップダウン内の "Hide from menu bar" オプションを使用して、メニューバーのゲージから非表示にしつつ、ドロップダウンの詳細には残すことができます。

コミュニティでの議論と代替案

Hacker News のコミュニティフィードバックでは、AI 使用クオータを追跡するさまざまな代替ツールが取り上げられています。claude-quota が macOS のメニューバーに焦点を当てている一方で、他のユーザーはターミナルや Claude Code のステータスラインに直接統合するツールを提案しています。

コミュニティで言及された代替ツールは次のとおりです。

  • CodexBar と usage4claude: Codex を含む複数のプロバイダーをサポートするツール。
  • ClaudeCodeStatusLine: Claude Code のインターフェースに使用データを直接追加するプラグイン。
  • codeburn、claudebar（Linux/Hyprland 用）、および RateLimited。

一部のユーザーは、このデータが Claude Code のステータスバーにネイティブに統合されることを望んでおり、残りの週次クオータの単純なパーセンテージ表示が外部プラグインよりもはるかに有用であると指摘しています。

Sources