Five Stream Deck keys mirroring the Plan usage limits panel on claude.ai/settings/usage:
| Key | Shows | Refresh |
|---|---|---|
| Current Session | NN% of your active 5-hour session + reset countdown |
3 min |
| Weekly (All Models) | NN% of your rolling 7-day all-models limit + reset countdown |
10 min |
| Weekly (Sonnet) | NN% of your weekly Sonnet limit |
10 min |
| Weekly (Claude Design) | NN% of your weekly Claude Design limit |
10 min |
| Extra Usage Credits | NN% of your monthly extra credits + used / limit in your currency |
10 min |
The percentage flips to coral when over 80%. Tap any key to open claude.ai/settings/usage in your browser. If the data fetch fails, the key turns into a coral !.
The numbers come straight from Anthropic's own usage endpoint — the same data your Settings page shows.
- Stream Deck app 6.5 or newer (Windows 10+ or macOS 12+)
- A signed-in Claude Code installation on the same machine. The plugin reads your OAuth token from
~/.claude/.credentials.json; if you've used Claude Code recently, it's there.
- Download
com.aaronholt.claude-usage.streamDeckPluginfrom the Releases page (or build it yourself — see below). - Double-click. Stream Deck offers to install it.
- In the Stream Deck app, find the Claude Usage category in the right sidebar.
- Drag the five actions onto adjacent keys.
The session key fills in within a few seconds and refreshes every 3 minutes; the weekly keys check on a 10-minute schedule but ride along on the session refresh whenever it happens — one HTTP call covers all five, shared via an in-memory cache.
git clone https://github.com/darhkfox/streamdeckclaude
cd streamdeckclaude
npm install
npm run build
npx @elgato/cli pack com.aaronholt.claude-usage.sdPluginThis produces com.aaronholt.claude-usage.streamDeckPlugin in the project root.
On every refresh the plugin makes a single authenticated GET to:
https://api.anthropic.com/api/oauth/usage
Authorization: Bearer <accessToken from ~/.claude/.credentials.json>
anthropic-beta: oauth-2025-04-20
The response contains five_hour, seven_day, seven_day_sonnet, seven_day_omelette (Anthropic's internal codename for Claude Design), and extra_usage (monthly pay-as-you-go credits) — each with { utilization, resets_at } (and currency/used_credits/monthly_limit for the extras). The plugin caches the response for 10 minutes and shares it across all five keys. If the access token is close to expiring, or a request returns 401, the plugin refreshes against https://console.anthropic.com/v1/oauth/token using the stored refreshToken and writes the new credentials back.
The endpoint is undocumented and heavily rate-limited, which is why polling is conservative (default: one shared HTTP call every 3 minutes).
The plugin only reads ~/.claude/.credentials.json and only sends those credentials to api.anthropic.com and console.anthropic.com — the same servers Claude Code itself talks to. Nothing leaves your machine that wasn't already going to Anthropic.
- Classic Stream Deck devices only (MK.2, XL, Mini, Neo). Stream Deck Plus dial/touch-strip support is not implemented.
- Anthropic's usage endpoint is undocumented and may change or break without notice.
- The endpoint rate-limits aggressively if polled faster than ~once per minute. The default 3-minute cache stays well below that ceiling.
npm install
npm run watch # rebuild on save
streamdeck dev # one-time, enables developer mode
streamdeck link com.aaronholt.claude-usage.sdPlugin
streamdeck restart com.aaronholt.claude-usage
streamdeck validate com.aaronholt.claude-usage.sdPluginAfter a code change, streamdeck restart reloads the manifest but does not kill the running Node child. Pick up TypeScript changes by also killing the plugin's node.exe process — Stream Deck respawns it with the new bundle.
Tunable constants live at the top of each src/actions/*.ts (refresh interval) and src/usage.ts (CACHE_TTL_MS).
MIT — see LICENSE.