---

Why you'll like it

• Native providers plus CodexBar: use focused native actions for Claude, Codex, Antigravity, Gemini CLI, MiniMax and OpenRouter; the optional CodexBar backend covers its configured providers from one action.
• Keys and dials: every action renders on standard keys and on Stream Deck+ encoders with a full dial layout.
• Live progress bars: color-coded usage (green, amber, red) plus human-friendly reset countdowns like 3h 33m or 4d 3h.
• Zero key juggling for most providers: reuses the credentials your existing CLIs already created locally. Only MiniMax and OpenRouter need a key pasted in.
• Always fresh: usage is polled and cached automatically, so the keys stay current without hammering provider APIs.
• Powered by a typed SDK: all the provider logic lives in the reusable @lenadweb/ai-limits library.

---

Install

From the Elgato Marketplace (recommended)

The easiest way, no build tools required:

Get AI Usage Limits on the Elgato Marketplace

Click Download, open the file, and Stream Deck installs the plugin automatically. Then find AI Usage Limits in the actions list and drag any provider onto a key or dial.

From source (for development)

# 1. Install dependencies
npm install

# 2. Build the plugin
npm run build

# 3. Develop with live reload (auto-restarts the plugin in Stream Deck)
npm run watch

Then open the Stream Deck app, find AI Usage Limits in the actions list, and drag any provider onto a key or dial.

---

Requirements

The plugin runs on both macOS and Windows. On macOS, Claude credentials are read from the Keychain; on Windows and Linux they are read from the credential file written by the matching CLI (see Provider setup).

---

Actions

Each provider is a separate action. All of them work on Keypad (keys) and Encoder (Stream Deck+ dials).

One metric per tile

Every action has a Layout setting:

• Bars (default) — the two-slot view, now with a metric picker for each slot.
• Ring — one large ring gauge showing a single metric, with its reset countdown in the middle.

Place the same action more than once to build a row of tiles, e.g. Claude Session, Claude Week, Codex Session and Codex Week side by side. Each tile keeps its own metric, and all tiles of a provider share a single API call, so extra tiles cost nothing. MiniMax and OpenRouter tiles carry their own API key, so they are fetched once per distinct key — several tiles on the same key still cost one call, and tiles on different keys each show their own account.

Claude note: besides the session and weekly windows, Anthropic reports weekly limits scoped to a single model, such as Fable. The plugin lists whichever ones your account returns, so they appear in the metric picker as Fable week (7d) without any setup. Accounts without scoped limits keep exactly the metrics they had.

Codex note: OpenAI currently exposes only a weekly window on Plus, Pro and Business plans (issue #6). The plugin classifies windows by the duration the API reports, so the weekly usage lands on the Weekly limit metric even when the API delivers it in the primary slot. A tile set to Session limit shows no data until OpenAI brings the 5-hour window back.

---

Provider setup

For most providers the plugin simply reads the credentials your CLI already wrote to disk, no copy-pasting tokens.

Tip: Make sure the matching CLI (Claude Code, Codex, Gemini CLI) is installed and logged in first; that is what creates the credential files the plugin reads.

---

CodexBar backend (optional)

The CodexBar backend action reads the local codexbar serve JSON API. It is useful for providers that do not have a dedicated native action here, while native actions remain independent and continue to work without CodexBar.

1. Install and configure CodexBar for the providers you use.
2. Start the local server: codexbar serve (the default address is 127.0.0.1:8080).
3. Drag CodexBar backend onto a key or dial.
4. Its settings automatically load enabled providers. Choose a provider, account, and one or two quota windows; use the refresh icon if you change your CodexBar configuration. A non-default local port can be set in Advanced before loading.

The plugin connects only to 127.0.0.1; it does not send CodexBar data or credentials to a remote host. CodexBar's desktop app and this backend action are macOS-oriented.

In addition to quota windows, the action exposes CodexBar's provider details and other displayable payload values, including credits, pace, identity, and data confidence. For OpenRouter this includes credits, API-key budget and spend, and the reported rate limit; each can be selected as a ring or bar metric.

In Advanced, you can start codexbar serve, see its status, and stop a server started by the current Stream Deck session. Server port and auto-start are shared by every CodexBar backend action, so multiple tiles use one server. You can also enable Start CodexBar automatically if it isn't running. This opt-in setting starts a locally installed CodexBar CLI only after the plugin cannot reach its configured loopback server.

---

How it looks

Each provider renders on both keys and Stream Deck+ dials, with a brand‑matched theme and a rounded usage bar that shows the reset countdown inside it.

---

How it works

The plugin is a thin rendering layer: it asks @lenadweb/ai-limits for a normalized usage summary per provider, then draws the progress bars and reset countdowns onto the key or dial.

---

Development scripts

---

Troubleshooting

• A provider shows no data: confirm the matching CLI is installed and logged in, and that its credential file exists (see the table above).
• Antigravity stuck after login: re-run Login from the Property Inspector; the token is cached at ~/.limits-streamdeck/antigravity_oauth.json.
• MiniMax shows an error: double-check the API key in the Property Inspector.
• Nothing appears after npm run watch: make sure the Stream Deck app is running and on version 6.9+.

---

Support

• Marketplace listing: AI Usage Limits on Elgato Marketplace
• Bugs & feature requests: GitHub issues

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before opening a pull request, and file ideas or bugs in the issue tracker.

---

License

MIT (c) lenadweb