導入手順
配布パッケージに付属のhelpも参照できます。
インストール
net.pupupu.ai-token-viewer.streamDeckPluginをダブルクリックし、Stream Deckでインストールします。- 「AI Token Viewer」→「AI利用枠の残量」をボタンへドラッグします。
- AIサービスを選択します。複数配置すれば各サービスを同時表示できます。
- 実際に接続する前に外観を確認したい場合は「デモデータ」をオンにし、確認後はオフに戻します。
Codex接続
Codexの既定パスは、Macでは /Applications/ChatGPT.app/Contents/Resources/codex、Windowsでは C:\Users\[user]\AppData\Local\OpenAI\Codex\bin\[version]\codex.exe です。Windowsの [user] は現在のユーザー、[version] はcodex.exeが存在する最新更新のビルドフォルダーへ自動解決します。アプリ更新後も毎回検出します。既存のカスタムパスは保持します。Windowsで対象がない場合はPATHのcodexを使用します。
各ボタンの「ChatGPTアカウントにログイン」からログインしてください。通常のcodex loginの認証情報は流用しません。実行ファイルが見つからない場合、「詳細設定:Codexアプリの場所」の入力欄にcodex.exeの絶対パスを指定してください。PowerShellで(Get-Command codex.exe).Sourceにより確認できます。.cmd / .batを指定せず、npm版ではそのパッケージ内のネイティブcodex.exeを指定します。
プラグインは30秒間隔で公式App Serverに読み取り要求を送り、終了させます。モデルへの質問は発行しません。Codexはボタンごとに独立した認証とキャッシュを使用します。長押しと設定画面の手動更新は、直前の取得開始から10秒以上経過した場合だけ実行します。手動取得後は30秒後に自動取得します。失敗した場合も30秒後に再試行します。旧バージョンの更新間隔設定は30秒へ移行します。
Macではターミナルで command -v codex を実行し、見つかった絶対パスを設定できます(例:/opt/homebrew/bin/codex)。手動で codex を指定した場合はPATHとHomebrewの標準パスを検索します。nvmなどで導入した場合は絶対パスを指定してください。[macOS導入ガイド](docs/macos.md)を参照してください。
Claude接続
PowerShellで次を実行します(インストール後)。
node "$env:APPDATA/Elgato/StreamDeck/Plugins/net.pupupu.ai-token-viewer.sdPlugin/bridge/setup-claude.mjs"
セットアップはホームフォルダーの.ai-token-viewerへ連携スクリプトをコピーし、Claudeのsettings.jsonにstatusLineを設定します。CLAUDE_CONFIG_DIRが設定されている場合はそちらを使います。変更前に設定ファイルのバックアップを保存します。既存のステータスラインがある場合は変更せず終了します。置き換える場合のみ同じコマンドの末尾に--replaceを付けて再実行します。
Claude Codeを再起動し、通常どおり使用してください。最初の応答後から利用枠のデータが出力されます。既定ファイルは%USERPROFILE%/.ai-token-viewer/claude-usage.jsonで、プラグインが30秒ごとに読み取ります。Claudeを使用していない間は最新情報を取得できません。既定10分で古いデータと表示します。長押しはファイルの再読み込みであり、Claudeへの問い合わせを発行しません。
既存ステータスラインと併用する場合は、元のスクリプトでstdinを一度だけ読み、同じJSONを元の表示処理と付属claude-statusline.cjsの両方へ渡してください。連携側のstdoutを捨てれば元の表示を維持できます。参考例はclaude-statusline-wrapper.cjsです。既存スクリプトの実行パスを設定してから利用してください。
WSLでClaudeを使う場合、Windowsとホームフォルダーが異なります。WSL側で連携を設定し、AI_TOKEN_VIEWER_CLAUDE_FILEにWindowsからも読める出力先(例:/mnt/c/Users/あなたの名前/.ai-token-viewer/claude-usage.json)を指定します。プラグイン側は対応するWindows絶対パスを指定します。WSL環境での実機試験は未実施です。
表示の意味
残量は100 − 使用率(0〜100に制限、小数点以下切り捨て)です。0.9%を1%と表示しないよう切り捨てています。取得できない値は--になり、100%として扱いません。リセット時刻を過ぎたデータも新しい情報を取得するまでは--です。古い情報には黄色い印と説明を表示します。リセット時刻はサービス側の値で、残り時間を推定して枠を復活させる処理はありません。
追加サービスの導入方法と制限は、このページの下部を参照してください。
macOS導入ガイド / macOS setup
macOS 13以降、Stream Deck 7.1以降が必要です。Windowsと同じ .streamDeckPlugin をダブルクリックしてインストールします。連携スクリプトにはNode.js 24以降が必要です。
Requires macOS 13+, Stream Deck 7.1+, and Node.js 24+ for bridges. Double-click the same .streamDeckPlugin installer used on Windows.
Codex
Codexの既定パスは、Macでは /Applications/ChatGPT.app/Contents/Resources/codex、Windowsでは C:\Users\[user]\AppData\Local\OpenAI\Codex\bin\[version]\codex.exe です。Windowsの [user] は現在のユーザー、[version] はcodex.exeが存在する最新更新のビルドフォルダーへ自動解決します。アプリ更新後も毎回検出します。既存のカスタムパスは保持します。Windowsで対象がない場合はPATHのcodexを使用します。
The default Codex path is /Applications/ChatGPT.app/Contents/Resources/codex on Mac and C:\Users\[user]\AppData\Local\OpenAI\Codex\bin\[version]\codex.exe on Windows. Windows resolves the current user and the most recently modified build containing codex.exe on each read, including after app updates. Existing custom paths are preserved. If no Windows desktop build is found, the plugin uses codex from PATH.
ターミナルで codex login を実行してChatGPTアカウントでログインします。手動で codex を指定した場合は、PATHに加えて /opt/homebrew/bin と /usr/local/bin を検索します。見つからない場合は command -v codex で確認した絶対パスを設定画面へ入力してください。nvmなどのNode.js管理ツールを利用している場合は、そのNode.jsのbinディレクトリをStream DeckのPATHにも含めて起動してください。
Run codex login in Terminal using ChatGPT. When explicitly configured as codex, the plugin searches PATH and standard Homebrew locations. If needed, enter the absolute path returned by command -v codex. For Node version managers such as nvm, launch Stream Deck with the corresponding Node bin directory in PATH so npm launchers can find Node.
Claude Code
ターミナルで実行し、Claude Codeを再起動します。既存ステータスラインがある場合は保持されます。併用方法はREADMEを参照してください。
Run in Terminal, then restart Claude Code. Existing status lines are preserved; see the README for chaining.
node "$HOME/Library/Application Support/com.elgato.StreamDeck/Plugins/net.pupupu.ai-token-viewer.sdPlugin/bridge/setup-claude.mjs"
Gemini CLI
実行後、Gemini CLIを再起動します。Run, then restart Gemini CLI.
node "$HOME/Library/Application Support/com.elgato.StreamDeck/Plugins/net.pupupu.ai-token-viewer.sdPlugin/bridge/setup-gemini.mjs"
Gemini API JSON import
既に取得した応答JSONを取り込みます。Import an existing API response JSON.
cat response.json | node "$HOME/Library/Application Support/com.elgato.StreamDeck/Plugins/net.pupupu.ai-token-viewer.sdPlugin/bridge/gemini-usage.cjs" --ai-studio
連携データは ~/.ai-token-viewer/ に保存されます。設定画面で変更する場合は /Users/名前/... の絶対パスを指定します(~ は入力しません)。
Bridge data is stored in ~/.ai-token-viewer/. Custom paths in the settings panel must be absolute /Users/name/... paths, without ~.
Cursor Teams
Teams管理者のAPIキーを、Stream Deckが継承する環境変数 AI_TOKEN_VIEWER_CURSOR_ADMIN_KEY に設定します。ターミナルの export だけではFinder起動のアプリには反映されません。以下はターミナルから起動する例です。Stream Deckを完全終了し、入力を画面表示・履歴保存しない形でキーを読み込みます。終了・再ログイン後などは必要に応じて再実行してください。
Set the Teams Admin API key in the environment inherited by Stream Deck. A Terminal-only export does not affect Finder-launched apps. Fully quit Stream Deck, then use this Terminal example to enter the key without displaying it or recording it in shell history. Repeat when needed after quitting or signing in again.
/bin/bash -c 'read -r -s -p "Cursor Teams Admin API key: " AI_TOKEN_VIEWER_CURSOR_ADMIN_KEY; printf "\n"; export AI_TOKEN_VIEWER_CURSOR_ADMIN_KEY; exec "/Applications/Elgato Stream Deck.app/Contents/MacOS/Stream Deck"'
標準以外の場所にStream Deckをインストールした場合は起動パスを変更してください。Adjust the application path for a nonstandard installation.
OS要件の出典 / OS requirements: Elgato system requirements.
Cursor Teams・Geminiの導入
サービスごとに指標が異なります。Cursor Teamsは追加利用予算、Gemini CLI・Gemini APIは直近に報告された使用トークン数を表示します。Geminiアプリの残量は取得非対応です。各サービスを同じ5H / 7D枠へ変換したり、契約プランから上限を推定したりしません。
廃止した連携と更新時の動作
CopilotのCLI内部通信を独自実装した取得処理は廃止しました。GitHubには公式SDKの利用枠取得APIがありますが、本プラグインの旧実装はSDKを利用せず内部トランスポートに依存していたため、維持しません。Copilotの取得コード・実行パス設定・選択肢を削除しました。
Geminiアプリの非対応項目も新規選択肢から除去しました。旧Copilot/Geminiアプリのボタンは「廃止された連携」として保持し、通信せず「取得非対応」を表示します。Codexなど別サービスへ勝手に切り替えることはありません。対応サービスを手動で選び直してください。
Gemini APIの項目は実態に合わせ「Gemini API · JSON import」に変更しました。AI Studioの画面連携ではありません。既存JSONのファイル名・内部識別子は互換性のため維持しています。
Cursor Teams
Teams管理者が作成したAdmin APIキーが必要です。個人Pro / Pro+ / Ultraアカウントの自動残量取得には対応していません。
- Windowsのユーザー環境変数
AI_TOKEN_VIEWER_CURSOR_ADMIN_KEYへAdmin APIキーを設定し、Stream Deckを完全終了して再起動します。 - 「Cursor · Teams」を選び、対象チームメンバーのメールアドレスを入力します。
公式POST https://api.cursor.com/teams/spendを読み取り専用で使用し、メールアドレスが完全一致するメンバーのみ表示します。残り%は100 × (1 − spendCents / (effectivePerUserLimitDollars × 100))です。これは追加利用の有効な個人予算に対する残量です。プラン内包枠・チーム全体の残量・実際にあと何回実行できるかを表しません。サービス側の集計遅延があります。上限が未提供・0・負数なら--とし、無制限や100%へ推定しません。リセット時刻も推定しません。
自動取得は5分間隔です。手動更新は他サービスと同じ10秒の間隔制限があります。管理キーは環境変数から読み取り、Stream Deck設定には保存しません。メールアドレスはStream Deck設定に保存されます。
Gemini CLI
AfterModelフックを備えたGemini CLIとNode.js 24以降が必要です。プラグインをインストール後、PowerShellで実行します。
node "$env:APPDATA/Elgato/StreamDeck/Plugins/net.pupupu.ai-token-viewer.sdPlugin/bridge/setup-gemini.mjs"
セットアップは.gemini/settings.jsonをバックアップし、既存のフックを保ったままAfterModelフックを追加します。スクリプトは.ai-token-viewer/gemini-usage.cjsへコピーします。Gemini CLIを再起動し、「Gemini CLI · Tokens」を選択してください。標準以外の設定ディレクトリやWSLでは、その環境の設定へ手動でフックを登録してください。フックが無効化されている環境では有効化が必要です。
llm_response.usageMetadata.totalTokenCountだけを、既定で%USERPROFILE%/.ai-token-viewer/gemini-cli-usage.jsonへ出力します。表示は直近の報告トークン数です。ストリーミングの各チャンクで報告される場合があり、セッション累計・日次使用量・契約残量ではありません。メタデータのないチャンクではファイルを更新しません。使用していない間は新しい値を取得できず、既定10分で古いデータと表示します。
Google AI Studio / Gemini API
Gemini APIから既に受け取った応答JSONの取り込みに対応します。AI Studioのブラウザー利用履歴・全プロジェクトのトークン数・RPM/TPM/RPDの残量は自動取得しません。
Get-Content -Raw response.json | node "$env:APPDATA/Elgato/StreamDeck/Plugins/net.pupupu.ai-token-viewer.sdPlugin/bridge/gemini-usage.cjs" --ai-studio
response.jsonはusageMetadata.totalTokenCountを含む実際のGemini API応答です。取り込みはモデルを呼び出しません。「Gemini API · JSON import」を選択すると、既定の%USERPROFILE%/.ai-token-viewer/ai-studio-usage.jsonを読み取ります。各取り込みで前回の値を置き換え、合算しません。応答の会話内容は連携JSONへ保存しません。
Gemini系の出力先を変更する場合は、連携スクリプトを実行する環境でAI_TOKEN_VIEWER_GEMINI_FILEを設定し、Stream Deckの「利用データJSONの絶対パス」も同じファイルに設定してください。Gemini CLIとAI Studioでは別々のファイルを使ってください。
Geminiアプリ
本実装では残量取得のための公開連携を確認できなかったため、自動取得は非対応です。新規選択肢には表示しません。Geminiアプリの使用量画面で確認してください。ブラウザーCookieの取り出しや非公開RPCによる取得は実装していません。
検証範囲
モックによる通信・取得失敗・表示切り替えのテスト、および実際の連携スクリプトを使ったローカルJSON生成を検証しています。各サービスの認証済みアカウントとStream Deck実機での追加サービスの接続確認は未実施です。