richhickson/claudecodeusage

macOS menu bar app showing Claude Code usage limits (session/weekly/per-model/overage) with alerts and click-to-focus when a Claude Code session needs your attention

Claude Usage – Anthropic Claude Code 用の macOS メニューバーヘルパー

概要 – メニューバーに常駐する軽量なネイティブ Swift 製 macOS アプリで、Claude Code の使用量クォータをリアルタイムで表示します。また、Claude Code セッションがユーザーの入力を待機しているときに通知を行い、セッションが実行されているターミナルタブへ直接ジャンプすることができます。

重要性 – Claude Code（Anthropic の Claude モデル用 CLI）は、セッションごと、週ごと、および月ごとの使用量制限を適用しています。これらの制限を監視しておくことで、予期せぬ超過料金の発生を防ぎ、セッションが静かに停止してしまうのを回避できます。

コア機能

機能	内容
使用量の追跡	現在のセッション使用量、週ごとの制限（Fable/Opus などのモデル固有の制限を含む）、および月間の超過支出を表示します。色（緑 < 70 %, 黄色 ≥ 70 %, 赤 ≥ 90 %）によって、即座に状況を確認できます。
自動更新	5 分ごとに Anthropic の使用量エンドポイントにクエリを送り、ネットワークやキーチェーンのトラブル時にリトライを行い、スリープ解除時に更新します。
セッション通知 (オプトイン)	Claude Code セッションが許可や入力を必要とする際、カウント付きのベルアイコンが表示されます。macOS の通知は切り替え可能で、通知またはリスト項目をクリックすると、該当する Terminal/iTerm2 タブへ直接ジャンプします。
ライブセッションリスト	ポップオーバー内で、追跡対象の各セッションの状態を表示します：要対応 🔔, 動作中 ⚙️, または完了 ✅。
Claude Code 設定エディタ	アプリからグローバルな `CLAUDE.md` ファイルを編集し、ローカルのトランスクリプトを保持する期間を制御する `cleanupPeriodDays` を調整できます。
便利機能	ログイン時の自動起動切り替え、内蔵のアップデートチェッカー、および軽量なフットプリント（ネイティブ Swift 製、追加のランタイムなし）を提供します。

内部的な仕組み

認証情報 – アプリは macOS の Keychain から Claude Code の OAuth トークンを読み取ります（パスワードがマシンから外部へ送信されることはありません）。
使用量データ – 未公開の Anthropic エンドポイント api.anthropic.com/api/oauth/usage を呼び出して、クォータ情報を取得します。
セッション監視 – 通知を有効にすると、アプリは ~/.claude/settings.json に小さな POSIX-sh フックを書き込みます。Claude Code は各セッションでこのフックを実行し、~/.claude/claudeusage/ に JSON 形式のステータスファイルを書き出します。メニューバーアプリは、そのディレクトリを監視して UI/通知を更新します。
クリックでフォーカス | macOS のアクセシビリティ権限を利用して、アプリが Terminal/iTerm2 に対して、セッション ID に一致するタブを選択するよう指示できるため、即座に対応可能です。

インストールと開始方法

ダウンロード – Releases ページから最新の ClaudeUsage.zip を取得し、解凍して ClaudeUsage.app を Applications フォルダへドラッグします。
初回起動 – 初回は右クリック → Open を選択します（macOS が署名なしアプリについて警告を表示します）。アプリは自動的に Claude Code の認証情報を検出します。
オプション – ソースからビルド – リポジトリをクローンし、ClaudeUsage.xcodeproj を Xcode で開き、⌘B でビルド、⌘R で実行します。
通知を有効にする – メニューバーのポップオーバー内にある歯車アイコンをクリックし、Alert when a session needs attention を切り替えます。アプリが ~/.claude/settings.json にフックをインストール/削除します。

必要条件

macOS 13 (Ventura) or newer
Claude Code CLI がインストール済み (npm i -g @anthropic-ai/claude-code) かつログイン済み (claude)

プライバシーとライセンス

テレメトリ（遠隔測定）なし。ネットワーク通信は Anthropic の公式使用量 API への呼び出しのみです。
MIT ライセンスのソースコード – 自由に監査や修正が可能です。
非公式ツール – Anthropic との提携関係はありません。変更される可能性のある未公開 API に依存しています。

Made by @richhickson