Cursor plan-usage adapter (usage.cursor.*)

[sebastientaggart]

Summary

Add a thin Deckhand usage plugin that publishes live Cursor plan/quota bars as usage.cursor.* state keys for OpenDeck Data Widgets — same normalized shape as Claude and Antigravity plan bars.

This is the next item on the usage widgets roadmap (Claude OAuth and Antigravity PATH CLI are shipped). It is not a multi-provider federation layer and does not reintroduce local JSONL burn analytics.

Proposed approach

Mirror claude_code_usage / antigravity_usage:

1. Read Cursor auth token from local storage (e.g. state.vscdb / cursorAuth/accessToken), same pattern as community status-bar extensions.
2. Poll Cursor usage endpoints on api2.cursor.sh (account-dependent):
   • Connect RPC GetCurrentPeriodUsage / planUsage (Pro / Team / Ultra — included spend in USD cents)
   • Legacy GET /auth/usage (Enterprise-style per-model request buckets)
3. Publish usage.cursor.* keys with { label, short_label, current, max, percent, unit, resets_at, updated_at, title } where percent is used % (0–100) for Data Widget percentage format consistency.

Suggested state keys (to refine during implementation)

key	meaning
usage.cursor.plan	Primary included allowance (spend or requests, normalized to %)
usage.cursor.<bucket>	Optional per-model buckets when /auth/usage applies

Non-goals

• Vendoring caut / CodexBar / ccusage
• Historical token burn from Cursor local logs
• Empty stub plugin module before the poller works

References

• Deckhand README “Usage widgets roadmap”
• Community patterns: Cursor status-bar extensions hitting api2.cursor.sh/auth/usage and dashboard Connect RPC
• Existing helpers: deckhand.integrations.usage_metrics.plan_bar_value