Codenotch（vinzdg/codenotch・GitHubスター1.5k・MIT）は、AIコーディングツールの利用上限をmacOSの画面端に常駐表示するアプリです。Claude Code・Cursor・Codex・Antigravityを筆頭に13プロバイダに対応し、各ツールの「セッション上限の何%を使ったか」を黒いノッチの中のリングで示します。ホバーすれば窓ごとの残量とリセット時刻、リングの内側の細い弧でエージェントが作業中か入力待ちかも分かります。2026年9月5日の公開から9日で1.5kスターに達しました。
背景は単純で、Claude・Cursor・Codexはどれもローリングのセッション窓で計量するのに、残量を見る手段は各アプリの /usage や設定画面に散らばっています。2〜3本を併用する人ほど「どれがまだ使えるか」を作業中に見失う。設計仕様の「The problem」はこの一点だけを問題として立てています。ただしベンダーは残量を返す公開APIを出していないので、Codenotchは各ツールが自分で使っている経路を借りて数字を取ります。本記事はその借り方と、それゆえの脆さを、READMEと設計仕様とソースから読み解きます。
- ・正体：macOS 15以降で動くSwift製の常駐アプリ。画面端の黒いノッチに13プロバイダの利用上限リングを並べる。MIT
- ・何ができる：残量%とリセット時刻の一覧、80%／100%到達の通知、エージェントの作業中・入力待ち・完了の表示、複数アカウント、スマホ連携、Windows移植版
- ・どう取る：手元のツールの認証情報やローカル状態を借りて各社の内部エンドポイントを読む。公式でない値には「~」を付け、失敗は捏造せず stale／needsAuth／error として見せる
- ・注意：ベンダーの内部仕様変更で読めなくなりうる（作者が明記）。本記事の執筆環境はLinuxで、実機起動は未検証。数値はソースの定数から
- ・勢い：公開9日で324コミット・v1.4.0→v1.10.0をほぼ毎日リリース・テスト73本
Claude Codeの上限そのものの仕組み（セッション窓・週次上限・プラン差）は、Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引きを起点に当サイトで整理しています。本記事はその「残量をどう見るか」の道具に絞ります。
Codenotchとは——13プロバイダの残量を1本のノッチに
設計仕様の一行目は「A macOS agent app that pins a small black side notch to the right edge of the screen showing, at a glance, how much of each LLM’s session limit you have burned」です。ノッチは4辺どこにでも置け、上辺に置いた場合はハードウェアのノッチと同じ形に合わせて一体に見せます。休止時は小さなピルで、ポインタが触れると展開します。
対応プロバイダはREADMEの表で13行あります。重要なのは「どこから読むか」が一律でないことです。
| プロバイダ | 数字の出どころ（READMEの記載を要約） | 信頼度 |
|---|---|---|
| Claude Code | Claude Desktopのキャッシュ → claude "/usage" → キーチェーンのOAuthトークン |
official |
| Cursor | エディタのローカルSQLite状態にあるサインイン済みセッション | official |
| Codex | ローカルのCodexサインインでChatGPTの利用量エンドポイント（5時間・週次） | official |
| Antigravity | ローカルの言語サーバ → Googleのクォータエンドポイント → 無理なら回数カウント | official／回数 |
| GitHub Copilot | gh auth login 済みのGitHub CLIセッションでCopilotクォータAPI |
official |
| GLM（Z.ai） | Claude Codeの settings.json・ZCode・OpenCodeのいずれかが持つキーを借用 |
official |
| Kimi／Grok／OpenCode／Command Code | 各CLIが保存した認証ファイル（~/.kimi-code/・~/.grok/auth.json 等） |
official |
| DeepSeek Platform | Codenotch自身のWKWebViewで明示サインイン → 残高・30日トークン | derived |
| Ollama（ローカル）／LM Studio | ローカルランタイムを自動検出。モデル・RAM/VRAM・tok/s・コンテキスト使用率 | local |
ローカルLLMの2行は上限ではなく稼働状況を出す変わり種です。Ollamaは OLLAMA_HOST=http://127.0.0.1:11435 で中継ポートを経由させると生成速度と思考中の表示が取れ、LM Studioは自身のSDKソケットとサーバログを読むので中継は不要、とREADMEにあります。プロバイダの並び順は設定画面でドラッグして変えられ、再度ONにしたものは末尾に付く（消えていたものが勝手に前へ割り込まない）という細部まで書かれています。
何が読めるか——「借りた認証情報」で数字を取る仕組み
Codenotchの核はプロバイダ抽象です。Sources/Providers/UsageProvider.swift のプロトコルは、fetchSnapshot() に加えて account()（誰の数字か）、signInRoute（サインインはどこでするか）、signOut()、forgetCachedCredential() を要求します。コメントには「借りた認証情報にはここで捨てるものは無い——セッションはClaude CodeやCursorのもので、終わらせるのは彼らの仕事」とあり、自分で作ったセッション（DeepSeek）だけが本当のログアウトを持つという線引きが明確です。
各アダプタは Fidelity を宣言します（Sources/Model/UsageModel.swift）。値は official・derived・manual の3つで、official以外の百分率には「~」の接頭辞が付きます。READMEの言い方では「UIが推測をベンダー公表値のように見せることは決してない」。
数字を集める UsageStore（Sources/Model/UsageStore.swift）の既定値は次のとおりです。
| 定数 | 既定値 | 意味 |
|---|---|---|
refreshInterval |
60秒 | 通常のポーリング間隔 |
idleRefreshInterval |
5分 | セッションが1つも動いていないときの間隔 |
staleAfter |
15分 | これより古い読み値は「stale」として薄く表示 |
localRefreshInterval |
1秒 | ローカルLLM（Ollama／LM Studio）の更新間隔 |
refreshDeadline |
60秒 | 1回の更新がこれを超えたら打ち切り |
失敗の扱いはUsageProviderErrorに細かく分かれています。needsAuth（サインインし直し）と accessDenied（キーチェーンの許可を拒否した）を区別しているのは、「サインイン済みなのにDenyを押した人に、壊れていないものを直しに行かせない」ためだとコメントにあります。
① 何ができる：13ツールの残量・リセット時刻・稼働状態を画面端で常時見られる。② 何を解決する：ツールごとに散らばった `/usage` や設定画面を見に行く手間と、上限到達に作業中で気づく事故。③ 何を代替できる：各ツールの `/usage` コマンドや使用量ページを「見に行く」行為。トークン単価の集計や課金額の計算は代替しない。
Claudeのリングはどこから数字を取るか
一番作り込まれているのがClaudeで、3段の読み込み順になっています。順序に理由があるので、ソース（ClaudeOAuthProvider.swift・ClaudeDesktopUsageCache.swift・ClaudeUsageCLI.swift）から追います。
1段目：Claude DesktopのHTTPキャッシュ。 Claude DesktopはChromium製アプリで、自身の使用量パネルが描く /usage 応答を ~/Library/Application Support/Claude 配下のHTTPキャッシュに書き出します。Codenotchはそこを読み取り専用で開き、自アカウントの組織IDに一致する /api/organizations/<id>/usage のエントリだけを対象にします。30分より古いスナップショットは「生きた値」として扱わず次へ落ちます。本文が content-encoding: zstd でmacOSにデコーダが無いため、Zstandardのデコード専用ビルドが Sources/Vendor/zstd（BSD-3-Clause）に同梱されています。ターミナルではなくDesktopで作業する人のリングが「真っ暗にならない」ためだけに、これだけの実装があります。
2段目：claude "/usage" の実行。 Claude Codeのバイナリをprintモードで起動し、/usage の出力を読みます。--print で作業ディレクトリの信頼ダイアログを避け、--no-session-persistence で1回ごとのトランスクリプト生成を防ぎます。タイムアウト20秒、呼び出し間隔は5分（cliRefreshInterval）。READMEの言葉では「Claude Code自身の /usage と同じ数字なので、2つが食い違うことがない」。
3段目：キーチェーンのOAuthトークン。 ログインキーチェーンのトークンで api.anthropic.com/api/oauth/usage を直接叩きます。これが最後の手段なのは、Claude Codeがトークン更新のたびに新しいキーチェーン項目を作り、新項目のアクセスリストにCodenotchが載らないため、「常に許可」が1時間ほどで効かなくなるからです。CONTRIBUTING.mdはさらに踏み込んで、GUIからは書けないパーティションリストの話まで説明しており、Scripts/fix-keychain-partitions.sh でTeam IDを登録する回避策を用意しています。
レートリミットの扱いも具体的です。Claudeのエンドポイントは叩きすぎると429を返し、Retry-After: 0 という役に立たない値が付く。Codenotchはこれを「床を上げる信号」とだけ解釈し、60秒から連続429ごとに倍増、上限15分でバックオフします。期限は永続化されるので、ペナルティ中に再起動しても試行を1回無駄にしません。
Claude Codeの /usage で何が見えて何が見えないかは、Claude Code 使用量 確認の6手段｜/usage で見えるもの・見えないものを実測で切り分けるで当サイトが実測しています。Codenotchの2段目はまさにこの /usage の出力を機械で読んでいるので、そこで見えないもの（例えばトークン単価ベースの費用）はCodenotchでも見えません。上限の数字そのものが直近で変わっている点はClaude Code 制限まとめ｜9/14に週次上限が恒久+25%＝今日比17%減、一次ソースで検証を参照してください。
「まだ動いてる？」——セッション状態の検出と完了通知
利用上限と並ぶもう1つの機能が、エージェントがいま作業中か・入力待ちか・終わったかの表示です。リングの内側で細い弧が回れば作業中、琥珀色に脈打てば入力待ち。仕組みはClaude Codeが書き出すファイルの監視で、ここが一番「他プログラムの内部仕様に乗っている」部分です。
（ディレクトリ監視＋2秒ごとの生存確認）"] --> B{"status フィールドはあるか？"} B -- "あり（ターミナルUIが書く）" --> C["busy / waiting / idle を
そのまま採用"] B -- "なし（Claude Desktop 経由のセッション）" --> D["トランスクリプトの末尾64KBを読む
~/.claude/projects/＜slug＞/＜sessionId＞.jsonl"] D --> E["inFlight / finished の2値
（waiting は判定できない）"] C --> F["SessionCompletionWatcher が
前回状態との差分だけを拾う"] E --> F F -- "busy → idle" --> G["ノッチを5秒開く＋システム音
クリックでそのアプリを前面へ"] F -- "busy → waiting" --> H["琥珀色に脈動＋別の音"] F -- "起動直後の初回読み取り" --> I["何も通知しない"]
ポイントは2つです。第一に、status はClaude Codeのターミナルインタフェースの描画ループだけが書くので、Claude Desktopが動かすセッションには存在しません（ClaudeTranscript.swift の冒頭コメント）。そのためDesktopのセッションはトランスクリプトの末尾から「ターン中か終わったか」を読みますが、権限プロンプトの記録が無いので「入力待ち」は判定できず、意図的に2値にしてあります。第二に、通知は状態ではなく遷移に対して出ます。起動時にすでに動いていたセッションは履歴が無いので通知せず、Claude Codeを終了してファイルが消えた場合も「戻る先の窓が無い」ので鳴らしません。
完了時にどのアプリを前面に出すかも、割り切った設計です。セッションはpidしか公開しないので、プロセスツリーを親へ辿って「起動元のアプリ」を見つけます。タブまで特定するにはターミナルごとのスクリプティング辞書が要り、WarpやGhosttyには無いため、アプリまでを前面に出してタブは人が選ぶことにした、とREADMEが理由ごと書いています。
通知のもう1系統が上限のアラートで、ヘッドラインの窓が80%を跨いだときと100%に達したときにシステム通知を1回だけ出します。跨いだままの間は繰り返さず、窓が本当にロールオーバーしてから再び鳴ります。macOSの通知権限は起動時ではなく最初の実アラート時に求めます。
Codenotchのインストールと設定——DMG・ソースビルド・複数アカウント
配布はGitHub Releasesの Codenotch.dmg で、公式リリースはDeveloper IDで署名・公証済み、Sparkleで毎日更新を確認して裏で入れ替えます（更新はEdDSA署名つき）。main の最新を試したい場合は preview タグのビルドか、Packageワークフローの成果物を使いますが、こちらはad-hoc署名なので隔離フラグを外す必要があります。
# preview ビルド（ad-hoc署名）を /Applications に置いたあと、隔離フラグを外す
xattr -dr com.apple.quarantine /Applications/Codenotch.app
READMEは「macOSが『壊れている』と言うのは隔離フラグのせいで、ダウンロード不良ではない」と補足しています。ソースからのビルドはXcodeGenでプロジェクトを生成する方式で、Apple Developerアカウントは不要です。
brew install xcodegen # 1回だけ。project.yml から .xcodeproj を生成する
make run # 生成→Debugビルド→起動
make test # ユニットテスト
CODENOTCH_DEMO=1 open /Applications/Codenotch.app # 固定のサンプルデータで表示を確認
Debugビルドはad-hoc署名で安定したコード識別子を持たないため、キーチェーンの「常に許可」が毎回リセットされます。ローカル開発でそれを避けるには Scripts/sign-local.sh で自己署名の固定IDを付ける、という手順まで用意されています。
複数アカウントはディレクトリ規約で扱います。Claude Codeを CLAUDE_CONFIG_DIR=~/.claude-work claude のように動かすと、~/.claude-<slug> が起動時に検出されて「Claude (work)」の別リングになります。既定の ~/.claude が常に先頭、残りはアルファベット順で、リングの順番は入れ替わりません。Codexも同様で、READMEに2つ目のアカウントをサインインさせる手順があります。
# Codex の2つ目のアカウントを別ディレクトリでサインインさせる（README記載）
mkdir -p "$HOME/.codex-work"
CODEX_HOME="$HOME/.codex-work" codex -c 'cli_auth_credentials_store="file"' login
以後そのアカウントのCLIも CODEX_HOME="$HOME/.codex-work" codex で動かし、Codenotchを再起動すると「Codex (work)」のリングが増えます。キーチェーンのみ・APIキーのみのCodexログインはChatGPTアカウントの上限を返せないので対象外です。
ウィンドウを持たないアプリなので、不具合の切り分けは統合ログで行います。
/usr/bin/log stream --predicate 'subsystem == "com.vinz.codenotch"' --level debug
project.yml はHardened Runtimeを有効、App Sandboxを無効にしています。理由も書かれており、CursorやCodexのSQLite／JSONを読むのは通常のファイルアクセスで、サンドボックスがそれを壊すから、とのことです。つまりこのアプリは設計上「他アプリの設定ファイルを読む」権限で動きます。READMEは読み取り専用・非送信を繰り返し明記していますが、それを信じるかどうかはMITのソースで確認できる、という位置づけです。
スマホ連携・Windows移植・開発ペース
スマホ連携は、Mac側の設定「Phone › Connect a Phone…」でQRコードを出し、iOS／Androidの専用アプリで読む方式です。プロトコルは docs/phone-link-protocol.md にv2として全文があり、脅威モデルの一行目は「LANの受動的な盗聴者が秘密を得てはならず、捕捉したリクエストは再送できず、古いQRのスクショは無価値でなければならない」。ペアリングコードは16バイト乱数の32桁hexで、5分間・1回限り、成功後は即座に更新されます。Macは既定でTCP 8788番を待ち受け、プライベートIPからの接続だけに応答します。送るのはノッチに出ている百分率・リセット時刻・セッション状態のみで、トークンや生のAPI応答は含みません。
Windows移植版は windows/ 配下にRust／Tauri 2で別実装されています（v0.3.0）。Swiftのコードは流用せず、対応はClaude・Codex・Cursor・Antigravityの4つ。ClaudeはClaude Codeが ~/.claude/.credentials.json に置くトークンで api.anthropic.com/api/oauth/usage を直接読み、macOS版のようなDesktopキャッシュ経由の段はありません。同じREADMEに「利用規約上の保証はしない」という注記もあります。
開発ペースは異常な速さです。初回コミットが2026-09-05、以降9日間で324コミット。日別では9月9日に73件、11日に72件。タグはv1.4.0（09-06）からv1.10.0（09-12）までほぼ毎日切られ、preview タグは毎コミットで作り直されます。テストは Tests/ に73ファイルあり、READMEの「every adapter’s response shape is pinned by tests」に対応しています。
| 日付 | 出来事 |
|---|---|
| 2026-09-05 | 初回コミット（プロジェクト名 Codenotch）。同日にGLMプロバイダ・複数Claudeプロファイル対応 |
| 2026-09-06 | v1.4.0 |
| 2026-09-07 | v1.5.0。ローカルLLM（Ollama）プロバイダの計画文書 |
| 2026-09-08 | v1.6.0（コミット44件） |
| 2026-09-09 | v1.7.0（コミット73件） |
| 2026-09-10 | v1.8.0。LM Studioプロバイダの計画文書 |
| 2026-09-11 | v1.9.0（コミット72件） |
| 2026-09-12 | v1.10.0（project.yml の MARKETING_VERSION も1.10.0） |
| 2026-09-13 | PR #172 をマージ。preview タグ更新 |
注意点と、類似手段との比較
Codenotchの弱点は作者が「The honest caveat」としてREADMEに書いています。どのベンダーも「セッション上限のN%」を返す整ったAPIを公開していないので、各アダプタは内部エンドポイント・ローカルDB・言語サーバのRPCを読み、それらは予告なく変わりうる。変わったときは数字を作らず stale／needsAuth／error に落とす、という約束です。Claude Desktopのキャッシュ形式についても「Chromiumのキャッシュ形式は非公開で変わりうる。変わったらこの経路は黙り、他の経路が引き継ぐ」と明記されています。
同じ「残量を知る」目的で使われる手段と並べると、Codenotchの守備範囲がはっきりします。
| 手段 | 見えるもの | 複数ツール | 常時表示 | 備考 |
|---|---|---|---|---|
Claude Code /usage |
セッション・週次の窓と残量 | Claudeのみ | ✕（打つたび） | Codenotchの2段目が読んでいるのはこれ |
| Claude Desktop の使用量パネル | 同上 | Claudeのみ | ✕ | Codenotchの1段目がキャッシュを読む |
| Cursor／Codexの設定・使用量画面 | 各社の上限とリセット | 各1つ | ✕ | ブラウザやアプリを開く必要がある |
| ccusage系のCLI | ローカルのJSONLからトークン数・推定費用 | Claude中心 | ✕ | 上限の窓は見ない。目的が違う |
| Codenotch | 13プロバイダの上限%・リセット時刻・稼働状態 | ○ | ○（画面端） | 各ツールの内部経路に依存。実機はmacOS 15+ |
導入判断の目安はこうなります。
・向く：Claude Code・Cursor・Codexを日常的に2本以上併用し、上限到達を作業中に踏むことがある人。エージェントの完了を待ちながら別作業をする人
・向かない：1ツールしか使わない人（その /usage で足りる）。費用や単価の集計が目的の人（Codenotchは%しか見ない）。他アプリの設定ファイルを読む常駐アプリを許容できない環境
・確認してから：READMEバッジの「macOS 26+」と本文・project.yml の「15.0」が食い違っている。ソース側の15.0を採ったが、実際の起動可否は自分の版で確かめる
Cursor側の上限とプランの関係はcursor 料金（Cursor pricing）2026｜Hobby・Pro・Pro+・Ultraの違いと選び方、Codex側の窓はCodex CLI 使い方｜インストール・料金・AGENTS.md・Claude Codeとの違い【2026年最新】で扱っています。Codenotchが表示する百分率は、それぞれの記事で説明している窓に対する消費率です。
本記事の検証環境について。 執筆環境はLinuxで、macOSアプリとしての起動・表示・通知は実機で確認できていません。記載は2026-09-13時点の main（コミット abccf0e・v1.10.0リリース後）のREADME・設計仕様・フォンリンク仕様・ソースを読んで裏づけたもので、間隔や閾値の数値はソースの定数、画面はリポジトリ同梱のデザインフレームです。実機での挙動が記述と異なる場合は、ソースの該当ファイル名を手掛かりに確認してください。
まとめ
claude "/usage"・キーチェーンの3段でClaudeの数字を取り、Cursor・Codex・Antigravityほか計13プロバイダを画面端のリングに並べる。失敗は捏造せず stale／needsAuth／error として見せ、公式でない値には「~」を付ける。エージェントの完了・入力待ちも ~/.claude/sessions とトランスクリプトから拾う。弱点は各ツールの内部仕様に乗っていること（作者が明記）と、他アプリの設定ファイルを読む権限設計。9日で324コミット・毎日リリースという勢いは追従力の裏づけでもあり、依存の多さの裏返しでもある。
・入れる前に：macOS 15以降か、Claude Code／Cursor／Codexのどれをローカルにサインイン済みか、キーチェーンのプロンプトを許容できるか
・入れたら：Settingsで不要なプロバイダをOFF（ポーリングも止まる）、80%通知の音を選ぶ、複数アカウントは ~/.claude-<slug>／~/.codex-<slug> 規約に合わせる
・壊れたら：リングが stale に落ちたら内部仕様変更を疑い、log stream の統合ログとGitHub Issuesを見る
参照ソース
・vinzdg/codenotch（公式リポジトリ・README・CONTRIBUTING.md・project.yml） — 対応プロバイダ・取得経路・配布形態・権限設定の一次情報。2026-09-13時点のmain（コミット abccf0e）を読解
・Codenotch — Design Spec（docs/specs/2026-08-28-usage-notch-design.md） — 問題設定・リングの色帯・UIの正本
・Codenotch Phone Link — protocol v2（docs/phone-link-protocol.md） — スマホ連携の脅威モデル・ペアリングコードの寿命・ポート
・ソース読解：Sources/Model/UsageStore.swift（ポーリング間隔）、Sources/Providers/ClaudeOAuthProvider.swift・ClaudeUsageCLI.swift・ClaudeDesktopUsageCache.swift（Claudeの3段）、Sources/Sessions/ClaudeSessionMonitor.swift・ClaudeTranscript.swift・SessionCompletionWatcher.swift（セッション検出）。git log・タグ・Tests/ のファイル数は2026-09-14に実測
