cursorhub 0.1.0

Desktop tray toast + CLI for your Cursor subscription usage

cursorhub

Track your Cursor subscription usage from a desktop tray toast or the terminal.

• Tray toast (cursorhub): an always-on-top card in the top-right corner showing your included-plan percentage, on-demand spend, and when the billing cycle resets. Refreshes every 5 minutes; dodges out of the way when your cursor gets near it.
• CLI (cursorhub usage, or the dependency-free standalone/cursor_usage.py): print usage on demand as a table or JSON.

How it works

Cursor stores a session JWT in its local VS Code-style state database (state.vscdb, key cursorAuth/accessToken). Your userId is the sub claim of that token. Cursor's own web dashboard authenticates to cursor.com/api/* with a cookie WorkosCursorSessionToken={userId}::{token}. cursorhub reads the token, builds the same cookie, and calls GET /api/usage-summary.

This needs no API key and works for any signed-in Cursor user - Pro, Business, or a member of an Enterprise team. You do not need to be a team admin (the official api.cursor.com/teams/* Admin API is admin-only; cursorhub does not use it).

The state DB is read from:

OS	Path
Windows	%APPDATA%\Cursor\User\globalStorage\state.vscdb
macOS	~/Library/Application Support/Cursor/User/globalStorage/state.vscdb
Linux	~/.config/Cursor/User/globalStorage/state.vscdb

Install

pip install cursorhub

Or from a checkout:

pip install -e .

The tray app needs PySide6 (pulled in automatically). The standalone script needs nothing but Python 3.11+.

Usage

cursorhub                       # launch the tray toast
python -m cursorhub             # same thing

cursorhub usage                 # print a table (your usage)
cursorhub usage team            # your usage plus team usage
cursorhub usage --json          # normalized JSON
cursorhub usage --raw           # raw Cursor API responses (debugging)

python standalone/cursor_usage.py           # no install required
python standalone/cursor_usage.py --json

Example table (cursorhub usage):

Cursor usage  -  [e-mail]  (enterprise)
====================================================
Included plan   [######------------------] 25.6%
                included 2000 + bonus 45 = 2045
On-demand (you) $0.00 / $300.00   left $300.00
Billing cycle   resets in 24d 13h   (2026-08-11T19:09:10.000Z)

  You've used 26% of your included total usage

With cursorhub usage team, team usage appears between the on-demand block and the billing cycle:

Cursor usage  -  [e-mail]  (enterprise)
====================================================
Included plan   [######------------------] 25.6%
                included 2000 + bonus 45 = 2045
On-demand (you) $0.00 / $300.00   left $300.00

Team usage
On-demand (team)$342.16 / $2,500.00   left $2,157.84

Billing cycle   resets in 24d 13h   (2026-08-11T19:09:10.000Z)

  You've used 26% of your included total usage

Configuration (env vars)

Variable	Purpose
CURSOR_SESSION_TOKEN	Use this raw JWT instead of reading the state DB
CURSOR_STATE_DB	Path to a non-default state.vscdb

Caveats

• These dashboard endpoints are unofficial / internal to Cursor and can change without notice. Every call degrades to a clear error rather than crashing.
• The session token expires when you sign out of Cursor. Sign back in and the tray toast recovers on its next refresh.
• On-demand amounts are reported by Cursor in cents and shown here in whole dollars.

License

MIT - see LICENSE.