cursor-usage

A Cursor agent skill that builds a billing-cycle usage report from your local Cursor session.

It answers three different questions without mixing them up:

1. How much quota is left (same % bars as Settings and OpenUsage)
2. Which chats and models are expensive (chargedCents list price)
3. What Stripe actually charged (subscription fee; overage only if on-demand is on)

The canvas report defaults to English and has an EN | 中文 toggle.

Three stills, sample data. Quota bars match Settings. Stacked bars split each chat by model. Table plus pie split Auto/API and IDE / Grok Bot / Cloud. Detail rows keep tokens and the mix.

Install

Copy or clone this folder to the shared skills root, then link every runtime at it:

npx skills add chocolatemale/cursor-usage

Or clone once and link every runtime:

git clone https://github.com/chocolatemale/cursor-usage.git ~/.agents/skills/cursor-usage
ln -sfn ~/.agents/skills/cursor-usage ~/.cursor/skills/cursor-usage
ln -sfn ~/.agents/skills/cursor-usage ~/.claude/skills/cursor-usage
ln -sfn ~/.agents/skills/cursor-usage ~/.codex/skills/cursor-usage

In Cursor, invoke /cursor-usage.

Listed on agentskill.sh.

What it fetches

flowchart LR
  A[state.vscdb / Keychain] --> B[WorkosCursorSessionToken]
  B --> C[usage-summary]
  B --> D[filtered usage events]
  B --> E[sand usage status]
  C --> F[Quota bars *PercentUsed]
  D --> G[List price by chat and model]
  E --> H[Grok Bot weekly pool]
  F --> I[Canvas report]
  G --> I
  H --> I

Loading

Personal accounts have no official usage API. The script uses the same unofficial dashboard routes as OpenUsage, CodexBar, and tokscale. It never prints the session token, email, or display name.

python3 ~/.agents/skills/cursor-usage/scripts/fetch_cursor_usage.py
# writes /tmp/cursor-usage/report.json

Three rulers

Ruler	Field	Use for
Quota	totalPercentUsed / autoPercentUsed / apiPercentUsed (denominator 100)	Remaining allowance
Included $	plan.used / plan.limit in cents (Ultra SKU = $400)	Whether the advertised included bucket is booked full
List price	Event chargedCents	Ranking chats and models

used == limit on the included-$ counter is not "the month is over". OpenUsage does not draw that pair as the progress bar.

Settings mapping: Cursor Models ≈ Auto, Other Models ≈ API.

Report

The agent writes ~/.cursor/projects/<workspace>/canvases/cursor-usage.canvas.tsx.

• Four dollar stats stay visible next to the quota bars
• Built-in PieChart (no custom donut)
• Top 20 stacked bars with IDE / Grok Bot / Cloud icons
• Language toggle via useCanvasState("lang", "en")
• Chat titles stay in their original language

Interactive mock: docs/preview.html. Product shots: overview, stacked chats, models and detail.

Privacy

The published skill has no account emails, home paths, conversation UUIDs, or real chat titles.

The fetch script writes only aggregates and titles resolved from your machine into /tmp/cursor-usage/report.json. That file is gitignored. Do not commit it.

License

MIT