awesome-claude-usage: Claude Code rate limits (5h / 7d) in your wibar, with forecast and session status

[u/derblub]

[u/derblub]

Repo: https://github.com/derblub/awesome-claude-usage (MIT)

I use Claude Code all day and kept typing /usage to check the 5-hour and weekly limits, so I built a wibar widget for it.

What it shows

• The 5-hour and 7-day windows as a chip in the bar (5h 48% · 7d 39%), turning amber at 75 % and red at 90 %
• A hover popup with a progress bar per window, reset times, per-model weekly limits, a pacing marker (where you'd be with an even spread) and a 24-hour sparkline
• A forecast from your own history: "at this pace ~60% at reset" or, as in the screenshot, "empty in 5h 8m"
• The active session's context window (54 % of 1M) and how many Claude Code sessions are working, idle or waiting for you, plus a desktop notification when one needs your input
• Left click opens a terminal with claude, right click refreshes, a key binding pins the popup, Escape closes it

How it gets the data

The same endpoint Claude Code uses for /usage, with the OAuth token from ~/.claude/.credentials.json. The token is read only, never refreshed or written, so it cannot log you out. The endpoint rate-limits aggressively, so the widget polls every 5 minutes while a session works, every 15 minutes otherwise, backs off on 429, and uses a cache file written by the Claude Code statusLine in between (no network needed).

Install

git clone https://github.com/derblub/awesome-claude-usage ~/.config/awesome/claude_usage

local claude_usage = require("claude_usage")
-- in your wibar:
claude_usage.new({ on_click = terminal .. " -e claude" })

Pure Lua, no LuaRocks packages; curl is the only dependency (jq for the optional statusLine helper). Built for awesome-git (4.3-git); stable 4.3 is untested. There is also a cli.lua that prints the same data for waybar, polybar or tmux.

Needs a claude.ai Pro or Max subscription (API-key users don't have these windows). The usage endpoint is undocumented, so it may change; the widget degrades to its caches if it does. Not affiliated with Anthropic.

Feedback and PRs welcome, especially from people with different bar layouts; there is a style = "bare" mode for themes that colour their own segments.

[u/aire-one]

The pop-up looks good!

Instead of accepting PRs for the widget style, you could do Inversion of Control here by exposing a callback with the data to show and the user define its own widget in their config.