AI Token Viewer

Setup guide

The plugin package also includes a local help folder.

Quick start

  1. Install the .streamDeckPlugin file by double-clicking it. Requires Windows 10+ / macOS 13+ and Stream Deck 7.1+.
  2. Drag AI Token Viewer → AI Usage Remaining onto a key.
  3. Choose a service. Add multiple keys to display services side by side.
  4. 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

Privacy & data

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

New integrations have automated mock transport, error, UI-state and real local bridge tests. Authenticated live-service and physical Stream Deck verification remains outstanding.