Ccusage-mqtt — Claude Code (Anthropic) usage as 15 MQTT sensors with a mood-driven dashboard

Share your Projects!
1

I have been running Claude Code heavily for the last few months and got tired of alt-tab-ing to a terminal to check how close I was to the 5h rate limit. The Anthropic dashboard is per-request, not per-window, so it never told me what I actually wanted to know: "am I about to get rate-limited in the next 20 minutes?"

So I built ccusage-mqtt — a single Python process that publishes Claude Code usage to MQTT, and Home Assistant auto-discovers a device with 15 sensors including a mood enum (idle / normal / active / heavy) calibrated from the same burn-rate thresholds the Clawdmeter ESP32 firmware uses (github.com/HermannBjorgvin/Clawdmeter).

[ :up_arrow: drag the dashboard-preview.gif here from docs/assets/ in the repo so it uploads as an attachment — don't paste the GitHub URL ]

What you get

A single Claude Code Usage device with:

  • mood — idle / normal / active / heavy (the cardinal sensor — drives a Lovelace picture-entity card with mood-matched art)
  • session_pct / session_reset_minutes / session_status — Anthropic's 5h window (Pro / Max)
  • weekly_pct / weekly_reset_minutes / weekly_status — Anthropic's 7d window (Pro / Max)
  • burn_rate_pct_per_min — smoothed over a 4-min ring buffer
  • time_to_limit_minutes — derived
  • tokens_used / tokens_per_hour / spend_so_far_usd / spend_per_hour_usd — from ccusage (github.com/ryoppippi/ccusage)
  • block_elapsed_pct — how far into your current 5h block

Pro/Max and Enterprise plans both supported (Enterprise returns a different ratelimit-header schema — the parser handles both via a fallback chain).

Why MQTT, not a HACS integration

Two reasons:

  1. The publisher has to run where Claude Code runs — it reads ~/.claude/.credentials.json for the OAuth token. Most HA-OS users run HA on a separate box from their dev machine, so a HACS integration would have to do remote credential plumbing. MQTT lets the publisher live on the dev machine and the data flow into HA over the network you already have.
  2. No separate Anthropic API key. The publisher reuses Claude Code's existing OAuth token (with auto-refresh), so quota measurements reflect the actual plan you're on, not a separate dev-API quota.

Install (60 seconds)

git clone https://github.com/george-vice/ccusage-mqttcd ccusage-mqttpipx install ../setup.sh

Or use the Docker path — bundles Node + ccusage + Python in one image. Install instructions and a copy-paste Lovelace YAML are on the landing page: george-vice.github.io/ccusage-mqtt

Where it goes next

  • A dedicated Lovelace card that watches sensor.claude_code_usage_mood and renders the matching pixel-art frame (HACS-shippable once it exists)
  • A blueprint exchange listing for "alert when mood stays heavy for N minutes" (already shipped in the repo, posting separately)

It's MIT, v0.2.0 just tagged. Happy to answer questions about the architecture, the OAuth-token-vs-API-key tradeoff, or the Enterprise header parser. Feedback / ideas / PRs all welcome.

1 Like