Metadata-Version: 2.4
Name: cursorhub
Version: 0.1.2
Summary: Desktop tray toast + CLI for your Cursor subscription usage
Project-URL: Repository, https://github.com/pandiyarajk/cursorhub
Project-URL: Issues, https://github.com/pandiyarajk/cursorhub/issues
Author-email: Pandiyaraj Karuppasamy <pandiyarajk@live.com>
License: MIT
License-File: LICENSE
Keywords: cursor,cursor-ai,monitor,pyside6,toast,usage
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: User Interfaces
Requires-Python: >=3.11
Requires-Dist: pyside6>=6.6
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install cursorhub
```

Or from a checkout:

```bash
pip install -e .
```

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

## Usage

```bash
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  -  you@example.com  (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  -  you@example.com  (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](LICENSE).
