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 60s.
• 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 30s). 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.

Development

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

License

MIT