AI Coding Usage Meter Setup guide Privacy GitHub

Setup guide

Install, place a key, pick a metric. Two minutes, start to finish.

Before you start

Both Pro and Max plans work. Any metric your plan doesn't report shows -- rather than failing.

Linux: there's no official Stream Deck app for Linux, so the plugin can't be installed there. The data layer is plain Node and does run on Linux if you're building from source.

Install

The easy path: open the Elgato Marketplace listing and click Get. It installs straight into the Stream Deck app and updates itself from then on.

To install the packaged file by hand instead:

  1. Download com.saeedkolivand.claude-usage.streamDeckPlugin from the latest release.
  2. Double-click it, then choose Install.

Place a key

  1. In Stream Deck, find the AI Coding Usage Meter category in the actions list on the right.
  2. Drag Usage Meter onto any key.
  3. Select that key and pick a Metric in the property inspector below the canvas.
  4. Repeat on more keys for the other metrics.

Keys populate within a second or two of being placed.

Settings

Profile

Which Claude account the key reads. Most people have one and can leave this alone. If you run more than one — a work login and a personal one, kept apart with CLAUDE_CONFIG_DIR — set it per key, so one key watches work and the next watches personal, side by side on the same deck.

The dropdown lists every config folder found: ~/.claude and anything beside it holding a projects directory. If yours lives somewhere else entirely, choose the blank entry and type the path under Custom folder.

One caveat on macOS. Claude Code stores its token in the login Keychain under a single name, with no per-account variant, so only your default profile can read a token from there. A second profile needs its own .credentials.json inside its config folder; without one, its limit gauges show open Claude while tokens and cost still work, since those come from the transcripts on disk.

Metric

Which value the key shows: Carousel, Session or Weekly for live limits, or Tokens / Cost for today, the last 7 days, or your current session.

Auto-rotate and Interval (Carousel only)

Whether the carousel flips between its 5-hour and weekly faces on its own, and how many seconds between flips (default 10). Pressing the key always flips it immediately, whether or not auto-rotate is on.

5h and Weekly label and color (Carousel only)

Per-face label (defaults 5 HOURS and WEEKLY, localize freely) and base color. The percentage, bar, and countdown tints are derived from the base color you pick.

Subtitle (Tokens and Cost only)

Overrides the scope line under the value (today, 7 days, session). Handy for localization.

Amber and Red thresholds

The percentages where a live limit metric turns amber (default 50) and red (default 80).

User-Agent (Advanced)

Sent to the usage endpoint. It must start with claude-code/ (default claude-code/2.0.31). Bump it if Anthropic ever tightens the check.

If something looks wrong

The key says "open Claude"

The token has expired or can't be read. Launch Claude Code once, which refreshes it, and the keys recover on the next tick. On macOS you may also be getting a Keychain prompt in the background, approve it.

The key says "offline"

The usage endpoint couldn't be reached. Keys keep the last good value, so nothing is lost, and they recover on their own when the connection comes back.

A metric shows --

Your plan doesn't report that particular figure. This is expected, not an error.

Tokens and cost look low

These are parsed from Claude Code's local logs, which currently under-record input and output tokens, so totals lean low and cost is a lower bound. On Pro and Max you don't pay per token anyway, so the cost shown is notional equivalent API spend, useful for relative sense rather than as a real charge.

Good to know

Still stuck?

The README covers building from source and has a command for testing the usage endpoint directly. If that doesn't get you there, open an issue.