Setup guide
The plugin package also includes a local help folder.
Quick start
- Install the
.streamDeckPluginfile by double-clicking it. Requires Windows 10+ / macOS 13+ and Stream Deck 7.1+. - Drag AI Token Viewer → AI Usage Remaining onto a key.
- Choose a service. Add multiple keys to display services side by side.
- Press to cycle 5-hour limits, 7-day limits, and remaining credits. Hold at least 0.7 seconds to refresh.
Choose English, Japanese, or the system language. Ring / bar styles, dark / light themes, reset countdown, warning thresholds, and stale-data timeout are available; automatic refresh is 30 seconds (Cursor Teams: five minutes). Demo mode is always labeled and must be disabled to see real data.
Codex
Install a Codex CLI with codex app-server and account/rateLimits/read. Use Sign in to ChatGPT on each button. The usual CLI sign-in is not reused. API-key-only accounts do not provide these subscription limits. If codex cannot be found in PATH, enter an absolute path to the native codex.exe; shell launchers such as .cmd and .bat are not supported. On Windows, (Get-Command codex.exe).Source can locate the executable.
The plugin queries the official local App Server every 30 seconds and then stops it. It never starts a model turn. Only 300-minute and 10,080-minute windows from the codex bucket are shown. Separate model buckets and general ChatGPT message caps are not combined. Each Codex button has separate credentials and its own usage cache. Manual requests for each button have a 10-second cooldown measured from the previous fetch start. After a fetch, the next automatic request is scheduled 30 seconds later, including on failure. Previous interval settings migrate to 30 seconds.
Claude Code
Requires Claude Code 2.1.251+, a Pro / Max subscription providing rate-limit fields, and Node.js 24+ for the bridge. After installing the plugin, run in PowerShell:
node "$env:APPDATA/Elgato/StreamDeck/Plugins/net.pupupu.ai-token-viewer.sdPlugin/bridge/setup-claude.mjs"
This copies the bridge into your home directory and configures Claude's statusLine command, honoring CLAUDE_CONFIG_DIR. Existing settings are backed up before modification. If another status line exists, setup leaves it untouched. Use --replace only if you want to replace it. Alternatively, adapt claude-statusline-wrapper.cjs to forward the same input to both scripts.
Restart Claude Code. After a normal Claude response, supported quota fields are written to %USERPROFILE%/.ai-token-viewer/claude-usage.json. The plugin reads this every 30 seconds. It does not actively query Claude: inactive sessions produce no fresh data. The key marks data as old after ten minutes by default. Holding the key only rereads the file.
For WSL, set AI_TOKEN_VIEWER_CLAUDE_FILE in the Claude environment to a Windows-accessible destination and select the corresponding absolute Windows path in the plugin. WSL has not been device-tested.
Remaining credits
Codex displays the reported credits.balance, preserving zero and showing unlimited balances as ∞. Missing balances show --. These are usage credits, not earned rate-limit reset credits. Claude’s status-line bridge does not provide this balance; its third view explicitly shows “Not supported”. Quota reset countdowns apply only to the 5H / 7D views.
Accuracy and privacy
Remaining percentages are floored and clamped to 0–100. Missing windows show --. Once the reported reset time passes, the old percentage is hidden until new data arrives. No automatic reset is inferred. Connection errors retain the last known value with an explicit old-data indicator.
The bridge persists only quota percentages, reset times, a timestamp and schema version. It does not persist prompts, transcript paths, API keys or cookies. Codex handles its own account credentials and upstream requests. See the Privacy page for details.
Download the existing-status-line wrapper example
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 setup
Run these commands in PowerShell after installing the plugin. The second command imports an existing Gemini API response.
node "$env:APPDATA/Elgato/StreamDeck/Plugins/net.pupupu.ai-token-viewer.sdPlugin/bridge/setup-gemini.mjs"
Get-Content -Raw response.json | node "$env:APPDATA/Elgato/StreamDeck/Plugins/net.pupupu.ai-token-viewer.sdPlugin/bridge/gemini-usage.cjs" --ai-studio
- Copilot removed: The previous custom implementation of CLI-internal transport was removed. GitHub documents an official SDK quota API, but this plugin no longer implements Copilot retrieval. Legacy Copilot/Gemini App buttons remain disabled, without requests or automatic reassignment to another service. Select a supported service manually.
- Cursor Teams: Requires a Teams Admin API key in the Windows user environment variable
AI_TOKEN_VIEWER_CURSOR_ADMIN_KEYand a full Stream Deck restart. Enter the exact member email. Every five minutes the plugin reads/teams/spendand displays remaining per-user on-demand budget, usingspendCentsandeffectivePerUserLimitDollars. It does not measure included plan allowance or team-wide availability. Missing/nonpositive limits show--; resets are not guessed. Reporting may lag. Individual plans are unsupported. - Gemini CLI: Run the
setup-gemini.mjscommand above with Node.js 24+, then restart Gemini CLI. Existing hooks are preserved and settings backed up. The AfterModel bridge records only the latest reportedtotalTokenCount; streaming chunks may update it. This is not session/account usage or quota. Missing metadata leaves the previous snapshot unchanged; inactive data becomes stale. Default file:~/.ai-token-viewer/gemini-cli-usage.json. Custom settings directories and WSL require manual hook configuration. - Google AI Studio / Gemini API: Use the PowerShell import command above with an existing API response containing
usageMetadata.totalTokenCount. Select Gemini API / JSON import (legacy file names remain compatible). Default file:~/.ai-token-viewer/ai-studio-usage.json. Imports replace the last value; they neither query AI Studio browser history nor infer API quota or costs. SetAI_TOKEN_VIEWER_GEMINI_FILEand the inspector's JSON path to use a custom file; keep CLI and API data separate. - Gemini App: Automatic quota retrieval is unsupported. Check Usage in the app. CLI/API data does not represent the app's allowance.
New integrations have automated mock transport, error, UI-state and real local bridge tests. Authenticated live-service and physical Stream Deck verification remains outstanding.