CodexとClaude Codeの利用率をmacOSのメニューバーに常駐表示するアプリを作った
※アプリも本記事も全てCodexが書いています
CodexやClaude Codeを使っていると、「今の利用率はどれくらいか」「次のリセットまでどれくらいか」をすぐに確認したくなります。
そこで、CodexとClaude Codeの利用率をmacOSのメニューバーに常駐表示するネイティブアプリ「AI Usage Menubar」を作りました。
GitHubリポジトリはこちらです。
このアプリは非公式であり、OpenAIおよびAnthropicとは提携していません。画面に表示される利用率・期間・モデル名はアカウントや利用状況によって異なります。
できること
Codex版とClaude Code版は別々のメニューバーアプリとして動作します。
| Codex版 | Claude Code版 | |
|---|---|---|
| メニューバー | Codex 61% |
Claude 32% · W78% |
| 利用枠 | サブスクリプション枠 | セッション枠・週間枠 |
| 詳細表示 | リセット時刻、トークン数、文脈使用率 | 両利用枠のリセット時刻、モデル名 |
| データ取得 | Codexのローカルセッション | Claude CodeのstatusLine
|
| 追加のAPI通信 | なし | なし |
使用率はデフォルトで次のように色分けします。
- 0〜59%: 緑（余裕あり）
- 60〜84%: オレンジ（注意）
- 85〜100%: 赤（上限が近い）
しきい値や色は設定画面から変更できます。使用量ではなく残量で表示することもできます。
インストール
必要環境
- macOS 13以降
- Apple Silicon搭載Mac
- Xcode Command Line Tools
- CodexデスクトップまたはCodex CLI
- Claude版も使う場合はClaude Code
Xcode Command Line Toolsがない場合は、最初に次を実行します。
xcode-select --install
リポジトリを取得して、両方のアプリをビルドします。
git clone https://github.com/akh1r0ck/ai-usage-menubar.git
cd ai-usage-menubar
make build
生成物は次の2つです。
dist/ChatGPT Usage.app
dist/Claude Usage.app
Codex版だけを起動するなら次のようにします。
open "dist/ChatGPT Usage.app"
Claude Code版は、ビルド後にstatusLineの取得スクリプトを設定します。
python3 scripts/install-claude-capture.py
open "dist/Claude Usage.app"
設定後、Claude Codeを再起動して1メッセージ送信すると表示が更新されます。
常用する場合は、2つの.appを/Applicationsに移動してから、設定画面の「Macログイン時に自動起動」を有効にします。
データ取得の仕組み
このアプリでは、利用量を取得するための追加APIリクエストを行いません。どちらのデータフローもMac内で完結します。
Codex版: JSONLのtoken_countイベントを読む
Codexはセッションを~/.codex/sessions/**/*.jsonlに記録します。Codex版は更新時刻の新しいJSONLファイルから、最新のtoken_countイベントを探します。
主に利用するのは次の値です。
payload.rate_limits.primary.used_percent
payload.rate_limits.primary.resets_at
payload.rate_limits.primary.window_minutes
payload.info.total_token_usage.total_tokens
payload.info.model_context_window
ここで重要なのは、セッションログ全体を画面に出すのではなく、payload.type == "token_count"のイベントから利用量に必要な数値だけを取り出している点です。このため、会話本文の表示・保存・外部送信は行いません。
Codex版が表示するのはCodexのローカルセッションに記録された利用枠です。通常のChatGPT WebやChatGPTアプリ全体の使用量を表示するものではありません。
Claude Code版: statusLineをローカルに中継する
Claude CodeはstatusLineコマンドの標準入力にJSONを渡します。中継スクリプトは、受け取ったJSONを次のキャッシュへ原子的に更新します。
~/.claude/usage-menubar.json
メニューバーアプリはこのキャッシュを読み、短期のセッション枠と週間枠を個別に表示します。片方を取得できない場合は--%のままにし、10分以上更新されていないデータには⚠を付けます。
また、install-claude-capture.pyは~/.claude/settings.jsonの他の項目を保持したままstatusLineだけを設定します。既存のstatusLineがある場合は次のファイルへバックアップします。
~/.claude/usage-menubar-statusline-backup.json
元に戻すためのスクリプトも用意しています。
python3 scripts/restore-claude-statusline.py
macOSネイティブで実装した理由
実装はObjective-C + AppKitで、外部ライブラリには依存していません。
メニューバー常駐アプリでは、次の点を重視しました。
- メモリやCPUのオーバーヘッドを抑える
- macOSのライト／ダークモードとアクセシビリティに馴染ませる
-
NSStatusItem、NSPopover、NSUserDefaults、UserNotifications、ServiceManagementなどmacOS標準の仕組みをそのまま利用する - 配布物とビルド手順をシンプルに保つ
ステータスアイテム自体はNSStatusBar.systemStatusBarから作成し、クリック時にNSPopoverで詳細を表示しています。設定変更時は通知を飛ばし、アプリの再起動なしでフォント、色、しきい値、更新間隔などを再反映します。
設定画面
設定画面は次の6タブで構成しています。
- 一般: 自動更新、更新間隔、ログイン時の自動起動
- 外観: テーマ、フォント、文字サイズ、配色、しきい値
- 表示項目: サービス名、使用量／残量、詳細項目
- 通知: 注意・警告しきい値への到達通知
- データ: データフォルダ、設定の書き出し／読み込み
- 詳細: 診断情報とプライバシー情報
Codex版とClaude版の共通設定は同じNSUserDefaults suiteに保存し、NSDistributedNotificationCenterで変更を共有しています。どちらかのアプリで設定を変えると、もう一方にもすぐ反映されます。
通知は同じ利用枠に対して重複しないよう、リセット時刻としきい値の組み合わせを識別子として保存しています。
複数ディスプレイで使う
macOSの「ディスプレイごとに個別の操作スペース」が有効な場合、NSStatusBarの項目は各ディスプレイのメニューバーに反映されます。
「システム設定」→「デスクトップとDock」→「Mission Control」→「ディスプレイごとに個別の操作スペース」をオンにし、一度ログアウトしてください。
また、ディスプレイの接続・取り外しを検知したときはステータスアイテムを再挿入し、各画面の表示を更新します。
開発とテスト
全体のビルドとチェックは次のコマンドで実行できます。
make check
ここでは、次の項目をまとめて確認します。
- Codex版とClaude Code版のビルド
-
Info.plistの検証 - バイナリ形式とコード署名の検証
- Claude Codeの
statusLine設定・復元テスト - Codex・Claudeの利用量パーサーのテスト
- 設定の保存、色、コントラスト、エクスポート／インポートのテスト
- README用設定画面の画像サイズ検証
プロジェクトの構成は次の通りです。
.
├── Sources/ # Codex版・Claude版のAppKit実装
├── Resources/ # Info.plist
├── scripts/ # ビルドとClaude statusLine設定
├── docs/images/ # ドキュメント用画像
├── Makefile
└── README.md
実装して得られた知見
1. 「追加APIを叩かない」という選択は常駐ツールと相性が良い
利用率を頻繁に表示するツール自体がAPIクォータやネットワークを消費するのは避けたいと考えました。既にローカルへ到達している利用量情報を読み取る構成にすることで、APIキーの管理も不要にできました。
2. 異なるデータソースは共通のスナップショットに正規化する
CodexはJSONL、Claude CodeはstatusLineキャッシュと入力は異なります。それぞれをUsageProviderで読み込み、利用率、リセット時刻、期間、プラン、モデルなどの共通スナップショットに変換することで、UIと設定の共通化がしやすくなりました。
3. 「取得できない」と「古い」を分けて表現する
ローカルデータは、アプリが起動していても更新されないことがあります。未取得は--%、取得後に古くなった値は⚠付きと分けることで、「ゼロなのか」「未更新なのか」を誤解しにくくしました。
注意点
- 本アプリはローカルの非公開データ形式や、Claude Codeの
statusLine仕様に依存しています。製品側の仕様変更によって表示できなくなる可能性があります。 - APIキーや追加通信は不要ですが、ローカルファイルの配置が変更された場合は追従が必要です。
- Claude Codeで既存の
statusLineを使っている場合、インストーラーはその設定をバックアップしますが、表示そのもはAI Usage Menubar用に置き換わります。 - ログを共有してバグ報告する場合は、会話本文や個人情報を必ず除外してください。
おわりに
AI Usage Menubarを使うと、CodexとClaude Codeの利用状況を作業の流れを止めずに確認できます。
小さなメニューバーアプリですが、「ローカルデータだけで完結する」「異なるサービスの情報を共通モデルにそろえる」「macOS標準の機能だけで軽量に作る」といった、常駐ツール作りのヒントも詰め込みました。
不具合や改善案があれば、GitHubのIssueやPull Requestでお寄せください。