DankClaudeUsage

A DankMaterialShell DankBar widget that shows your Claude Code subscription limits — the rolling 5‑hour window and the weekly (7‑day) window — as theme‑colored rings with a detailed popout. Same numbers as Claude Code's /usage.

Zero setup: enable it and it works. It reads the OAuth token a Claude client (Claude Code or OpenCode) already stores on your machine and queries Anthropic's usage endpoint directly — no statusline edits, no config wiring.

Status: 0.1.0, experimental. The DMS plugin API is itself experimental and may change between minor versions.

What it looks like

Two bar styles, both using your active DMS theme palette (shifting primary → warning → error as a limit fills):

• Rings — a progress ring per limit with the percentage in the center (default)
• Numbers — ✳ 15% · 4%

Clicking the pill opens a popout with one row per limit, each showing the percentage and a live "resets in …" countdown, plus an "updated Xm ago" footer.

How it works

~/.claude/.credentials.json ─┐ (Claude Code OAuth token)
                             ├─▶ fetch-usage.sh ──GET──▶ api.anthropic.com/api/oauth/usage ──▶ ~/.cache/dms-claude-usage.json ──▶ plugin (QML)
~/.local/share/opencode/auth.json ─┘ (OpenCode OAuth token)

The widget runs the bundled fetch-usage.sh on a timer. The script gathers the access tokens that your Claude clients keep on disk — Claude Code's ~/.claude/.credentials.json and OpenCode's ~/.local/share/opencode/auth.json — prefers one that hasn't expired (freshest first), calls the usage endpoint (the same one /usage uses), normalizes the response, and writes a small cache file the widget renders. A short freshness guard means multiple monitors share one network call per interval. Reset countdowns tick client‑side.

Each client refreshes only its own token, and only while it runs. Reading every client means the widget stays current as long as you use any of them — it no longer goes stale just because you switched from Claude Code to OpenCode.

Privacy/security: the token never leaves your machine except in the request to api.anthropic.com — exactly where the clients themselves send it. The widget only reads tokens; it never writes credentials.

When it can't fetch: if no client is signed in, or every stored token has expired and no recent client run has refreshed one, the popout says so and the widget keeps showing the last values. Running Claude Code (or OpenCode) refreshes its token automatically.

Requirements

• DankMaterialShell with the plugin system (requires_dms >= 0.1.0)
• jq and curl
• A Claude client signed in on a Pro/Max plan — Claude Code (claude → /login) or OpenCode

Install

Clone the repo straight into the DMS plugins directory:

git clone https://github.com/bogdan-velicu/DankClaudeUsage \
          ~/.config/DankMaterialShell/plugins/claudeUsage

Then in DMS: Settings → Plugins → Scan, enable Claude Usage, and add it to a DankBar section (Settings → DankBar Layout). That's it — it starts showing usage within a few seconds.

Settings

Setting	Default	Notes
Display style	Rings	rings (% in the center) or numbers (✳ 15% · 4%)
Show 5‑hour limit	on
Show weekly limit	on

Rings shift primary → warning → error as a limit fills. The thresholds (70/90), refresh interval (5 min), and stale window (1 h) are named constants at the top of ClaudeUsageWidget.qml / ClaudeUsageData.qml — tweak them there if you like.

Cache format

{
  "captured_at": 1781090000,
  "five_hour":  { "used_percentage": 15, "resets_at": 1781091000 },
  "seven_day":  { "used_percentage": 4,  "resets_at": 1781575200 }
}

resets_at is Unix epoch seconds.

Development & tests

sh tests/test-fetch.sh      # fetch-usage.sh: response normalization, error handling (no network)
sh tests/test-manifest.sh   # plugin.json validity

tests/test-fetch.sh exercises the normalization against fixtures/oauth-usage-sample.json via the script's CLAUDE_USAGE_MOCK hook, so it never hits the network. The QML widget is verified by loading it in a DMS instance (see docs/superpowers/ for the design and build plan).

License

MIT — see LICENSE.