AI Token ViewerSetup guide
The plugin package also includes a local help folder.
Quick start
1. Install the .streamDeckPlugin file by double-clicking it. Requires Windows 10+ and Stream Deck 7.1+.
2. Drag AI Token Viewer → AI Usage Remaining onto a key.
3. Choose Claude Code or Codex. Add two keys to display both services.
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 fixed at 30 seconds. 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. Sign in through codex login with ChatGPT. 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. Requests are shared across keys using the same executable. Manual requests share 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/com.kmgxx.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.