CodenotchでmacOS上のコーディングアシスタントの利用上限を確認する

Codenotchとは？

Codenotchは、画面の端にコンパクトな黒いノッチを固定表示するmacOSアプリです。リングには、対応する各コーディングアシスタントの使用上限のうち、どれだけ消費したかが表示されます。また、セッションがアクティブ、完了、入力待ちのいずれの状態かも確認できます。

アイドル時、ノッチは小さなピル状で表示され、ポインタが近づくと展開します。プロバイダーのリングにカーソルを合わせると、使用上限の期間とリセット時刻が表示されます。Claude Codeでは、メインリングにClaude Codeの/usageコマンドで最初に表示される現在のセッション期間と同じ情報が表示されます。

Codenotchはセッションのアクティビティも監視します。セッションが処理中の間は、プロバイダーリング内で細い弧が回転します。セッションに対応が必要になると、リングが脈動するアンバー色に変わります。カーソルを合わせると、実行中のセッション名、実行場所、必要な対応が表示されます。

対応プロバイダーとデータソース

Codenotchは独自のアカウントシステムを管理せず、サインインを求めることもありません。Mac上の対応ツールがすでに保持している認証情報またはセッションを読み取ります。

• Claude Code：ログインキーチェーンに保存されたOAuthトークンを使用し、Claude Codeの/usageコマンドと同じエンドポイントに問い合わせます。
• Cursor：ローカルのSQLite状態から、エディタにサインイン済みのセッションを読み取ります。
• Codex：実行中のCodexアプリサーバーに現在のレート制限を問い合わせます。Codexが実行されていない場合は、ロールアウトログにフォールバックします。
• Antigravity：まずローカルの言語サーバーを試し、次にGoogleのクォータエンドポイントを試します。どちらからもアカウントのクォータデータを取得できない場合は、単純なリクエスト数を表示します。
• GLM：Claude Codeのsettings.json、ZCode、またはOpenCodeがすでに保持しているキーを使って、Z.aiのCoding Planモニターエンドポイントを呼び出します。

対応ツールを通常どおりインストールしてサインインしてください。Codenotchがそのローカルセッションまたは認証情報を検出すると、対応するリングが表示されます。設定でプロバイダーを無効にすると、Codenotchはその認証情報の読み取りを停止し、保存済みの読み取りデータを削除します。元のツールからサインアウトすることはありません。

主な機能

• Claude Code、Cursor、Codex、Antigravity、GLMの使用状況リング。
• リングにカーソルを合わせると、リセット期間の詳細を表示。
• コーディングセッションの処理中および入力待ち状態をリアルタイム表示。
• 複数のClaude Code設定を自動検出。
• 画面の上、下、左、右の端に配置。
• 使用可能な画面領域、Dockの位置、ハードウェアノッチに応じてレイアウトを調整。
• Dockアイコン、メニューバーアイコン、またはどちらも表示しない設定。
• Sparkleによる毎日のバックグラウンド更新チェック。
• 推定パーセンテージではなく、stale、needsAuth、error状態を明示。

Codenotchのビルドと実行

前提条件

このプロジェクトはXcodeGenで生成されたmacOSアプリケーションです。HomebrewでXcodeGenを一度インストールしてください。

brew install xcodegen

リポジトリをローカルにチェックアウトした状態で、プロジェクトを生成し、ビルドして、Debugビルドを起動します。

make run

Debugビルドに署名IDは必要ありません。

テストの実行

プロジェクトのテストターゲットを使用して、プロバイダーアダプターやその他の動作を検証します。

make test

基盤となる内部エンドポイント、ローカルデータベース、RPCインターフェースは予告なく変更される可能性があるため、プロバイダーのレスポンス形式はテストで固定されています。

デモデータの使用

ライブのプロバイダーデータを読み取らずにインターフェースを確認したい場合は、CODENOTCH_DEMO=1を指定してアプリを起動します。

CODENOTCH_DEMO=1 make run

デモモードでは固定のサンプルデータが使用され、インターフェース開発、レイアウト確認、スクリーンショットの撮影に役立ちます。

make releaseは通常のローカルセットアップには含まれません。Developer ID証明書とApp Store Connectの公証プロファイルが必要で、メンテナーがアーカイブ、公証、署名済み自動更新フィードの生成に使用します。

基本的な使い方

1. プロバイダー独自のツールからサインインする

監視したいコーディングツールを開き、そのツールからサインインします。Codenotch自体がサインイン処理を行うことはありません。たとえば、通常どおりClaude CodeまたはCursorで認証してから、Codenotchを起動します。

2. プロバイダーリングを確認する

検出された各プロバイダーは、ノッチ内にリングとして表示されます。リングで、使用可能な上限のうちどれだけ消費したかを確認できます。カーソルを合わせると、使用可能な上限期間とリセット時刻を確認できます。

3. セッションの状態を確認する

対応セッションが処理中の間は、リング内で細い弧が回転します。脈動するアンバー色のリングは、セッションが停止してあなたの対応を待っていることを示します。カーソルを合わせると、セッション名、場所、求められている操作を確認できます。

4. ノッチを設定する

ノッチの下にあるオーブから設定を開きます。オーブは静止時には弧として表示され、カーソルを合わせると歯車になります。設定では、カーソルを合わせたときにノッチを展開するか、常に表示するか、完全に非表示にするかを指定できます。

CodenotchにDockアイコン、メニューバーアイコン、またはどちらも表示しない設定も選択できます。

5. 画面の端を選択する

ノッチは4つの端のいずれかに配置できます。

• 左または右：プロバイダーの読み取り結果が縦方向に並びます。
• 上または下：プロバイダーの読み取り結果が横並びになります。

Codenotchは画面の使用可能な端に合わせて動作します。下側に配置するとDockの上に収まり、Dockが自動的に隠れたり移動したりするとそれに応じて反応します。ハードウェアノッチのあるMacでは、上側への配置にその正確な形状を使用するため、物理ノッチとソフトウェアノッチが1つの要素のように表示されます。

複数のClaude Codeアカウントを監視する

Codenotchは、Claude Codeの設定ディレクトリごとに別々のリングを表示できます。たとえば、仕事用アカウントを次のように起動します。

CLAUDE_CONFIG_DIR=~/.claude-work claude

Claude Codeがそのディレクトリを使用すると、Codenotchが検出し、個人用アカウントの横にClaude（work）リングを表示します。仕事用アカウントには、独自の制限、セッション、設定項目が適用されます。

起動時、CodenotchはClaude Codeが使用した~/.claude-<slug>形式のディレクトリを検索します。デフォルトの~/.claudeアカウントは常に先頭に配置され、追加の設定はアルファベット順に並べられるため、リングの位置が予期せず変わることはありません。

更新動作とレート制限

Codenotchは、不要なリクエストを減らすためにポーリング間隔を調整します。監視対象のセッションが実行されていない場合、ポーリングは5分ごとに遅くなります。最新の値を手動で取得するには、ノッチを右クリックして今すぐ更新を選択します。

Claudeのエンドポイントは、短時間に何度も問い合わせるとHTTP 429を返すことがあります。Codenotchは60秒から始まる遅延を適用し、レート制限の応答が連続すると遅延時間を倍増させ、最大15分まで延長します。この期限は起動後も保持されるため、再起動直後に別の試行を消費することはありません。

更新とセキュリティ

CodenotchはSparkleを使用して毎日更新を確認し、バックグラウンドでインストールします。自動更新は設定で無効にできます。公式の更新にはEdDSA署名が付与されているため、メンテナーが作成・署名していないビルドがアプリにインストールされることはありません。

キーチェーンを使用するプロバイダーでは、公式アプリが安定したDeveloper IDのIDを使用するため、1回の常に許可の許可設定を再ビルド後も維持できます。Codenotchは、秘密情報を再度読み取る前にキーチェーン項目の変更日を確認し、通常のポーリング中にアクセス許可を繰り返し求めることを減らします。

高度な開発メモ

プロバイダーアーキテクチャ

各連携機能はSources/Providers/配下でUsageProviderを実装します。プロバイダーは、.official、.derived、.manualのいずれかのFidelity値も宣言します。これにより、ベンダーが直接公開した値であるかのように推定値を表示することを防ぎます。

Sources/Model/配下にあるUsageStoreは、タイマーでプロバイダーをポーリングし、最後に成功した読み取り値を起動後も保持します。プロバイダーが失敗した場合、ストアはパーセンテージを捏造する代わりに、stale、needsAuth、errorなどの目に見えるステータスを公開します。

画面端のレイアウト

ノッチのレイアウトは、alongとacrossの座標を使い、1次元のスタック空間で動作します。NotchPlacementは、選択した画面端に応じてこれらの値を実際の画面座標にマッピングします。NotchLayoutは、実装とデザインフレームを比較するための寸法を一元管理します。

診断ログの確認

Codenotchには従来型のアプリウインドウがないため、診断情報はmacOSの統合ログに書き込まれます。次のコマンドでデバッグメッセージをストリーム表示できます。

/usr/bin/log stream --predicate 'subsystem == "com.vinz.codenotch"' --level debug

これは、プロバイダーが認証できない場合、古いデータを返す場合、または応答形式が変更された場合に使う主要なトラブルシューティングツールです。

制限事項を理解する

対応しているベンダーの中に、コーディングセッションの使用量を正確なパーセンテージとして普遍的に報告する、単純で安定したAPIを公開しているものはありません。そのためCodenotchは、エンドポイント、データベース、言語サーバー、ログなど、各アプリケーションが使用する内部またはローカルの情報源から読み取ります。

これらのインターフェースは予告なく変更される可能性があります。Codenotchはアダプターテストと明示的な失敗状態によってこのリスクに対応していますが、上流アプリケーションの変更後、一時的にプロバイダー連携が機能しなくなることがあります。

まとめ

Codenotchは、コーディングアシスタントの使用量、リセット期間、アクティブなセッション状態を、小さなmacOS画面端ディスプレイにまとめます。まずmake runを実行し、デモモードで安全にインターフェースを確認してから、対応ツールですでに設定されているアカウントをアプリに検出させてください。開発やコントリビューションの詳細については、CONTRIBUTING.mdを参照してください。プロジェクトはMIT Licenseの下で公開されています。