Claude Usage

A Claude Code usage plugin for CloudCLI Cloud and CloudCLI UI

CloudCLI Cloud · Discord · Bug Reports · Plugin Docs

---

Claude Usage — CloudCLI Plugin

Shows the current usage of Claude Code in a CloudCLI tab:

• Live plan limits — session (5h window), weekly, and per-model utilization gauges with severity coloring and reset countdowns, straight from the same endpoint that powers Claude Code's /usage screen. Auto-refreshes every 5 minutes (the endpoint is strictly rate-limited, see below).
• 30-day history — daily token bar chart, totals (tokens / estimated cost / sessions), and per-model / per-project breakdowns, parsed locally from ~/.claude/projects/**/*.jsonl transcripts.

Installation

Open Settings > Plugins in CloudCLI UI, paste this repository's URL, and click Install. Or manually:

git clone https://github.com/HandyS11/cloudcli-plugin-claude-usage.git ~/.claude-code-ui/plugins/claude-usage
cd ~/.claude-code-ui/plugins/claude-usage
npm install && npm run build

How it works

The backend subprocess (dist/server.js) exposes two endpoints via the host's RPC proxy:

• GET /live — reads the OAuth token from ~/.claude/.credentials.json and calls https://api.anthropic.com/api/oauth/usage (cached 5 minutes). It never writes to the credentials file and never uses the refresh token; if the token is expired it asks you to run claude to refresh it.
• GET /history?days=30 — parses local session transcripts (deduped by message id, cached by file mtime) and aggregates tokens and estimated cost by day, model, and project. Costs use a bundled price table; unknown models show "—".

Both sections fail independently — no credentials still shows history, and vice-versa.

Note: the usage endpoint is unofficial and may change; the live section degrades gracefully if it does.

Rate limiting

The usage endpoint allows only a handful of requests per window, and that budget is shared with Claude Code's own /usage screen and statusline (see anthropics/claude-code#30930). To stay well under it, the plugin:

• calls the endpoint at most once every 5 minutes, no matter how many tabs are open or how often you click refresh (concurrent requests share one call);
• on HTTP 429 honors Retry-After when present, otherwise backs off 5 → 10 → 20 → 40 → 60 minutes between attempts;
• keeps showing the last good reading (marked as stale, with the reason) while it waits, instead of blanking the gauges.

Development

npm install
npm test        # tsc + node --test dist/
npm run dev     # tsc --watch

License

MIT