UsageButtons

UsageButtons

Stream Deck plugin that turns every AI-coding-assistant usage stat into a live button — session % remaining, weekly %, credits, reset countdowns, per-model quotas, and more. Each button renders a dynamic icon whose background fills (or de-fills) in proportion to the current value, so you can tell at a glance how much runway you have left.

Inspired by CodexBar for macOS. Runs on Windows and macOS.

Settings

Each provider is its own action — drag Claude, Codex, Gemini, Vertex AI, etc. onto a key and configure the metric, colors, and thresholds from the Property Inspector.

Provider auth methods and selectable metrics are listed in docs/PROVIDERS.md.

Per-button settings	Plugin-wide defaults

Runtime

Written in Go. Compiles to a single static binary per platform — no runtime dependencies. End users just install the plugin; the Stream Deck software launches the binary directly.

• Single binary, no runtime dependencies
• Low memory footprint
• Only external dep: coder/websocket

Repo layout

UsageButtons/
├── io.github.anthonybaldwin.UsageButtons.sdPlugin/  # Stream Deck plugin bundle
│   ├── manifest.json
│   ├── ui/                               # Property Inspector HTML
│   ├── assets/                           # icons shipped with the plugin
│   └── bin/                              # compiled binaries (gitignored)
├── cmd/
│   ├── plugin/                           # Go entry point
│   └── native-host/                      # Chrome native-messaging bridge
├── chrome-extension/                     # MV3 companion extension (fetch-proxy)
├── docs/                                 # landing page, screenshots, provider reference
├── internal/
│   ├── streamdeck/                       # SD WebSocket protocol
│   ├── render/                           # SVG button renderer + bbox
│   ├── cookies/                          # browser fetch-proxy client + bridge
│   ├── providers/                        # provider interface, cache, mock
│   │   ├── abacus/                       # Abacus AI (browser)
│   │   ├── alibaba/                      # Alibaba Coding Plan (browser/API key)
│   │   ├── amp/                          # Amp (browser)
│   │   ├── antigravity/                  # Antigravity (local language server)
│   │   ├── augment/                      # Augment (CLI/browser)
│   │   ├── claude/                       # Claude (OAuth + browser web API)
│   │   ├── codex/                        # Codex (OAuth)
│   │   ├── cookieaux/                    # cookie-gated provider messaging helpers
│   │   ├── copilot/                      # GitHub Copilot
│   │   ├── cursor/                       # Cursor (browser)
│   │   ├── factory/                      # Droid / Factory (browser/token)
│   │   ├── gemini/                       # Gemini CLI OAuth
│   │   ├── jetbrains/                    # JetBrains AI
│   │   ├── kilo/                         # Kilo
│   │   ├── kimi/                         # Kimi (browser/token)
│   │   ├── kimik2/                       # Kimi K2 (API key)
│   │   ├── kiro/                         # Kiro
│   │   ├── minimax/                      # MiniMax (browser/API key)
│   │   ├── mistral/                      # Mistral (browser)
│   │   ├── ollama/                       # Ollama (browser)
│   │   ├── opencode/                     # OpenCode (browser)
│   │   ├── opencodego/                   # OpenCode Go (browser)
│   │   ├── openrouter/                   # OpenRouter (API key)
│   │   ├── perplexity/                   # Perplexity (browser)
│   │   ├── synthetic/                    # Synthetic (API key)
│   │   ├── vertexai/                     # Vertex AI (gcloud ADC)
│   │   ├── warp/                         # Warp (GraphQL)
│   │   └── zai/                          # z.ai (API token)
│   ├── settings/                         # global + per-key settings
│   ├── icons/                            # provider SVG glyph paths
│   ├── update/                           # GitHub Releases update checker
│   └── httputil/                         # shared HTTP+JSON helpers
├── scripts/                              # build, release, icon generation
├── tmp/CodexBar/                         # upstream reference (gitignored)
├── CLAUDE.md                             # Claude-specific agent notes
├── AGENTS.md                             # shared agent instructions
└── README.md

Install

The full step-by-step lives on the landing page. Short version:

1. Download the .streamDeckPlugin bundle for your OS from the latest release and double-click to install in Stream Deck.
2. (Optional, for browser-backed providers) Grab UsageButtons-Helper-unpacked.zip from the same release, unzip it, and Load unpacked in chrome://extensions. The plugin auto-registers — nothing to configure.
3. Drag a provider (Claude, Codex, Copilot, etc.) onto a Stream Deck key and pick a metric from the Property Inspector.

Build from source

git clone https://github.com/anthonybaldwin/UsageButtons.git
cd UsageButtons
go build -o io.github.anthonybaldwin.UsageButtons.sdPlugin/bin/plugin-win.exe ./cmd/plugin/
go build -o io.github.anthonybaldwin.UsageButtons.sdPlugin/bin/usagebuttons-native-host-win.exe ./cmd/native-host/
./scripts/install-dev.sh --restart

install-dev.sh junctions the .sdPlugin folder into Stream Deck's plugin directory so rebuilds take effect without reinstalling. Cross-compile with GOOS=darwin GOARCH=arm64 go build ... for macOS (and the same for the native host — releases build both arches via the release workflow).

Full dev workflow lives in AGENTS.md.

Releases

Cut via the manual release GitHub Action — no local git work:

gh workflow run release.yml --field bump=patch
gh workflow run release.yml --field bump=minor
gh workflow run release.yml --field bump=custom --field custom_version=0.4.0
gh workflow run release.yml --field bump=patch --field draft=true  # draft release

The workflow bumps both manifests, tags, builds plugin + native host for Windows + macOS (both arches), packages the Helper zip, and publishes the release with all three artifacts attached.

Usage Buttons Helper (required for browser-backed metrics)

Some providers sit behind browser sessions instead of public API keys. Usage Buttons ships a small Chrome extension — Usage Buttons Helper — in chrome-extension/ that proxies fetch() for the narrow allowlist used by those providers. Your usage reads happen through your real browser session; cookies never leave Chrome.

• No credentials in the plugin. credentials: "include" + Chrome's native cookie jar. The plugin only sees API response bodies.
• Narrow by design. Hardcoded to fetch only the provider origins in internal/cookies/allowed.go — enforced in the manifest's host_permissions AND again in the service worker at request time. No cookies permission, no broad host scope.
• One-click install. The extension's ID is pinned by its public key, so the plugin auto-registers the native-messaging bridge on launch — download the release zip, Load Unpacked in chrome://extensions, done.
• Providers that don't need it keep working unchanged — Gemini, Vertex AI, Copilot, OpenRouter, Warp, z.ai, Kimi K2, Synthetic, Kilo, Kiro, JetBrains AI, and Antigravity never require the extension.
• Waits patiently on cold start. Cookie-gated buttons stay in a quiet "needs browser extension" state until the extension handshakes — so launching Stream Deck before Chrome doesn't trigger a 403 loop.

Install steps live in the Helper README. Works in any Chromium-based browser (Chrome, Edge, Brave, Chromium); a Firefox port is on the roadmap.

License

MIT · Third-party licenses