DeckBridge for Cursor · Manual

User manual

Everything DeckBridge for Cursor does, key by key. To install and sign in, follow the setup guide.

1. Welcome

DeckBridge for Cursor is a Stream Deck plugin for macOS. It keeps your Cursor usage meters live on keys: percentage used, reset countdown and spend, in a colour ring that turns amber and then red as you near a limit.

  • You sign in to Cursor once, in a Chrome window that belongs to the plugin alone.
  • After that the meters refresh themselves in the background.
  • Holding a meter key opens the real Cursor dashboard.
  • A value that couldn't refresh is marked STALE instead of being shown as fresh.

DeckBridge has no telemetry and no DeckBridge account or service (Privacy).

2. Requirements

Operating systemmacOS 13 or later.
Stream Deck appVersion 7.1 or newer.
BrowserGoogle Chrome, installed as a normal application in /Applications or in your user Applications folder (~/Applications). Chrome Beta, Canary, Chromium, Brave and Edge don't count.
Cursor accountAn account that can open Cursor's spending dashboard. The model meters need a paid plan (Plans).
Anything elseNothing. No Node.js, command line, browser extension or helper app.

3. Installation and first run

  1. Get DeckBridge for Cursor from the Elgato Marketplace. It installs into the Stream Deck app.
  2. Drag the actions you want onto keys (place the keys).
  3. Sign in to Cursor, then check sign-in, until the Setup & Status key says READY.

Leave DeckBridge's Chrome window open after READY. You can minimise it, but don't close it (How refresh works).

4. The actions

Place any of them on any key. All of them share one connection and one check, and every one has the same settings panel, so Setup & Status is a convenience, not a requirement. No bundled profile is needed.

Setup & StatusOptional key. Shows sign-in and connection state, never usage numbers.
Cursor Models UsageMonthly percentage used of the Cursor Models quota, with the reset countdown.
Other Models UsageMonthly percentage used of the Other Models quota, with the reset countdown.
Grok Bot UsageWeekly percentage used of the Grok Bot quota, with the weekly reset countdown.
On-Demand SpendMonthly on-demand dollars spent, against your cap.
Weekly Pool UsageNew plans: the shared weekly pool, percentage used, with the weekly reset countdown.
Prepaid BalanceNew plans: your individual prepaid USD credit remaining.

Legacy plans can keep the four original meters in a 2 × 2 block. New plans can use Weekly Pool Usage and Prepaid Balance beside Setup & Status.

Key presses

  • Short press any key while connected: refresh every applicable meter now.
  • Hold a legacy meter (about a second): open the Cursor spending dashboard in one visible window. Holding a new-plan meter opens the Grok dashboard.
  • Hold Setup & Status: open help.

5. Reading a meter key

  • Percentage meters (Cursor Models, Other Models, Grok Bot, Weekly Pool): the name on top, the percentage used in the middle, MONTHLY or WEEKLY below it and RESET plus the countdown (for example RESET 30d) at the bottom.
  • Ring colour: teal below 70%, amber from 70% to 89%, red from 90%.
  • On-Demand Spend: dollars spent in the middle. OF $50.00 style text shows your cap and the ring shows spend against it. NO LIMIT means uncapped (muted ring). OFF means on-demand is disabled on your account.
  • Prepaid Balance: your remaining credit in dollars, with USD REMAINING.
  • Reset countdowns repaint locally every minute between checks, with no extra request.

Other faces

…Loading.
↻ (footer)Refreshing.
STALE (footer)The last check failed, so the key shows the last good value.
SIGN INCursor needs a sign-in.
PRESS / AFTER SIGN INSign-in is pending. Finish it in the Chrome window, then check sign-in.
ERRORA terminal failure. Open the settings panel for the cause.
N/AThat meter doesn't apply to your plan.
FREE / FREE PLANA free Cursor plan has no usage cards to meter.
FREE / NEEDS PROOn-Demand Spend on a free plan: it needs a paid plan.

6. The Setup & Status key

An optional key that shows connection state only, never usage values. Its footer always reads HOLD FOR HELP.

  • Short press moves setup along: it opens the sign-in window, checks sign-in, refreshes when ready, or retries after an error.
  • Hold (about a second) opens help.

The faces are in Key states.

7. The settings panel

Select any DeckBridge action in the Stream Deck app. The panel is the same for every action and never receives usage numbers, spend, balances, dashboard content, account identity, cookies or tokens.

Action nameWhich action you selected.
StatusSigned out, Sign-in pending, Connected, Needs attention or Working, with a plain-language explanation and, for an error, a one-line fix.
Main buttonChanges with the state: Sign in to Cursor, Check sign-in, Refresh now or Retry. When Grok sign-in is needed it reads Sign in to Grok.
Sign in againAlso Start sign-in again while sign-in is pending. Restarts authentication, and reopens the dedicated Chrome window if you closed it.
Open dashboardOpens the Cursor spending page in a visible window. Available when connected or in error, and Chrome is present.
ChromeGoogle Chrome available, not found, or status unknown.
Last updateThe last successful refresh, or "No successful refresh yet".
Clear local sessionAsks for confirmation (section 14).
LinksSetup, Privacy and Support.
Version and support codeThe plugin version, and your support code (section 15).

8. How refresh works

  • One background check refreshes every placed meter together, every five minutes, and after your Mac wakes from sleep. A short press refreshes at once.
  • The check runs in DeckBridge's dedicated Chrome session. It reads Cursor's usage data through your signed-in session, without opening the dashboard in a window.
  • Keep DeckBridge's Chrome window open. Updates need it. Minimise it if you like. If you close it, updates can stop. Choose Sign in to Cursor (or Sign in again) in the settings panel to reopen it, then Check sign-in.
  • If Chrome restarts the dedicated session by itself, DeckBridge reconnects without showing a window. If the session was fully quit and nothing can be reconnected, sign-in is needed again.
  • A window opens only when you ask: sign-in, Open dashboard, holding a meter key, or a help link.
  • The dedicated Chrome session never touches your normal Chrome profile.
  • When a check fails: keys keep the last good value marked STALE. After one or two failures in a row the Setup & Status key stays READY; the third shows ERROR. Any success resets the count. A sign-in expiry, a missing Chrome or a changed dashboard format shows at once, and the cached meters are cleared when sign-in or the data's integrity is the problem.

9. Plans

Paid, legacy plansCursor Models, Other Models, Grok Bot and On-Demand Spend.
New unified plansWeekly Pool Usage (the shared weekly pool) and Prepaid Balance (your individual prepaid USD credit). Supported since version 1.0.4. These plans need the linked Grok account signed in, in the same dedicated Chrome window. If the key asks, choose Sign in to Grok, finish sign-in, then Check sign-in. DeckBridge doesn't switch plans or link accounts for you.
Free planThe model meters show FREE with your usage-reset countdown, and On-Demand Spend shows NEEDS PRO. The connection still reads READY.
A meter that doesn't applyShows N/A. The connection is healthy and the other keys stay live. A confirmed plan change replaces readings that no longer apply.

A plan's name alone doesn't say which kind it is: both legacy and new plans have an Ultra tier. DeckBridge detects it from your account.

10. Key states

The Setup & Status key. The same steps are in the setup guide.

Key showsMeaningWhat to do
WORKINGAn operation is running.Wait.
SIGN IN (grey)No Cursor session yet.Short-press to open the sign-in window.
CHECK LOGIN (blue)The sign-in window is open and not yet verified.Finish signing in, leave Chrome open, short-press to check.
READY (teal)Connected. The meters are live.Nothing.
ERROR (red)Three checks in a row failed, or something needs you.Open any action's settings panel.

A meter key shows STALE, SIGN IN, N/A and the other faces in section 5.

11. Privacy and what is read

  • DeckBridge never reads, enters or stores your Cursor password. You sign in yourself, in the dedicated window.
  • It uses a dedicated Chrome profile and never reads or ends your normal Chrome. Cursor treats that profile as a new browser once, so expect its usual verification the first time.
  • Chrome connects to cursor.com and, for new plans, grok.com, plus their sign-in services and the page resources those sites need. Pages you open on purpose, such as help links, use the network too.
  • DeckBridge adds no telemetry and no DeckBridge service. Usage numbers are drawn on your deck and stop there.
  • Only derived numbers are cached: percentages, countdowns, spend and balance, with the time of the last successful check. Page text, account details, credentials and cookies are never logged or cached.
  • The support code is generated on your Mac, holds no usage or account value, and isn't uploaded.

See the privacy policy.

12. Limitations

  • macOS only. There is no Windows version yet.
  • Google Chrome only, from /Applications or ~/Applications.
  • Chrome must keep running. Closing DeckBridge's window can stop updates.
  • Prepaid Balance is your individual USD balance. Team balances aren't supported.
  • On-Demand Spend shows no reset countdown.
  • The data comes from Cursor's own dashboard endpoints, which aren't a public API. If Cursor changes them, a meter can show an error or STALE until DeckBridge is updated.
  • Keys are keypad keys only. There are no dial actions.

13. Troubleshooting

Google Chrome was not foundInstall the stable channel of Google Chrome in /Applications or ~/Applications, then retry.
The network is unavailableRestore the connection, then retry.
The usage dashboard is unavailable, or a refresh timed outRetry, or use Open dashboard to see Cursor's own page.
Cursor's dashboard format has changedOpen Support. Existing values stay as STALE.
This metric is not available on the current planCheck your Cursor plan or dashboard. The connection stays ready.
Sign in to GrokSign in to the Grok account linked to your Cursor subscription, in the same dedicated Chrome window, then Check sign-in.
Updates stoppedThe dedicated Chrome window may have been closed. Choose Sign in to Cursor or Sign in again, then Check sign-in, and leave the window open.
The local session could not be clearedOpen Support. The session is kept.
Keys show STALE or ERRORSee section 8 and the FAQ below.

14. Clearing the session and uninstalling

  • Clear local session is in every action's settings panel, behind an explicit confirmation. It removes DeckBridge's dedicated Cursor Chrome session and the cached meter values, and nothing else. Your normal Chrome profile, your Cursor account and your other plugins aren't touched. Your support code is kept.
  • If any check of the request fails, the plugin refuses and keeps the session and cached display.
  • To uninstall, clear the local session first if you want no trace left, then remove the plugin in the Stream Deck app, as for any plugin.

More in the setup guide.

15. Getting help

  • Email support@deckbridge.io with your support code (shown at the bottom of every settings panel). It holds no usage or account value.
  • The support page has the FAQ and a contact form.
  • Holding the Setup & Status key opens help.
  • Purchases, receipts and refunds are handled by Elgato through the Marketplace.

16. Frequently asked questions

Why does a Chrome process keep running in the background?

It holds your signed-in Cursor session so the meters can refresh every five minutes without ever showing you a browser window. It uses a dedicated profile that belongs to the plugin alone, opens a window only when you explicitly ask (sign-in, or holding a key to open the dashboard), and never touches your normal Chrome profile. Quit it fully and the meters simply can't refresh until you sign in again.

I'm on a free Cursor plan - what do the meters show?

Free plans don't expose the per-model usage cards (Cursor Models, Other Models, Grok Bot) or on-demand spend on the spending dashboard, so there's no percentage to meter. DeckBridge recognises a free plan and shows the meters as FREE with your shared usage-reset countdown (e.g. RESET 30d), and marks on-demand as needing Pro - the connection still reads READY. The four live meters need a paid Cursor plan (Pro or above); upgrade and they fill in on the next refresh.

Why does Cursor say it doesn't recognise my browser when I sign in?

Because it doesn't - and that's deliberate. Sign-in happens in DeckBridge's dedicated Chrome profile, which has never met cursor.com, so Cursor runs its usual new-device verification even if you're signed in elsewhere. Your normal browser's session is intentionally never used or read - that isolation is the plugin's privacy promise. Complete the verification once; the dedicated session persists from then on and sign-in is rarely needed again.

Does DeckBridge ever see my Cursor password or account details?

No. You sign in to Cursor (and, on new unified plans, Grok) yourself, in the dedicated Chrome window - DeckBridge never reads, enters or stores credentials. The keys show derived numbers only: percentages, reset countdowns and spend. Raw dashboard content, account identity, cookies and tokens are never cached, logged or sent anywhere. The privacy policy has the complete picture.

Does it work with Cursor's new unified plans?

Yes, since version 1.0.4. Place Weekly Pool Usage (your shared weekly pool) and Prepaid Balance (your individual USD credit). These plans need the linked Grok account signed in, in the same dedicated Chrome window: if a key asks, choose Sign in to Grok, finish signing in, then Check sign-in. DeckBridge doesn't switch plans or link accounts for you.

Which sites does DeckBridge connect to?

Chrome, in DeckBridge's dedicated profile, contacts Cursor's usage services and, for new unified plans, Grok's usage and billing services, plus their sign-in services and the page resources those sites need. DeckBridge adds no telemetry and no DeckBridge service: usage numbers are drawn on your deck and stop there.

A key shows STALE - is my data wrong?

No - stale means honest. A routine check failed (network blip, laptop just woke, Cursor slow to respond), so the key keeps the last good value and says so instead of quietly posing as fresh. It usually heals on the next five-minute check; short-press any key to retry immediately.

Setup & Status shows ERROR - what now?

Open any DeckBridge for Cursor action's settings panel in the Stream Deck app - it names the exact problem and offers the fix. The common one is an expired Cursor sign-in, which is just the two setup steps again: Sign in to Cursor, then Check sign-in. ERROR appears when three checks in a row have failed or something genuinely needs you; one-off blips only ever show STALE.

It says Chrome was not found, but I have Chrome

DeckBridge looks for Google Chrome in /Applications and in your user Applications folder (~/Applications). If Chrome lives anywhere else, move or reinstall it into one of those two locations. Chrome Beta, Canary, Chromium, Brave and Edge don't count - the plugin drives the regular Google Chrome application only.

I quit Chrome completely and now it asks me to sign in again - why?

When the dedicated Chrome process is fully quit, DeckBridge verifies any replacement process actually belongs to it before trusting it with your session. If Chrome restarted itself, DeckBridge reconnects automatically without opening a window. If no verified replacement exists, it fails safe and asks you to sign in again rather than guess - two key presses and you're back.

One meter says its metric is unavailable, but the others work

Your Cursor plan doesn't show that card on the spending dashboard, so there is nothing to meter - the connection itself is healthy and the other keys stay live. The settings panel says the same. If the card exists on your dashboard but the key disagrees, email us with your support code.

Does it work if my system language isn't English?

Yes. The dedicated Chrome session reads the dashboard in English regardless of your system language - the plugin sets that up itself. Your own browsing and your Cursor account settings are unaffected.

What is the support code in the settings panel?

A random identifier generated on your machine, shown in every action's settings panel. Include it when you email us - it lets us correlate a conversation without you sharing anything sensitive. It contains no usage numbers, no account details, and is never uploaded anywhere by the plugin.

Is there a Windows version?

Not yet - DeckBridge for Cursor is macOS-only today (macOS 13 or later). Windows is on the roadmap after launch; join the launch list on the product page and you'll hear about it.

What exactly does Clear local session remove?

DeckBridge's dedicated Cursor Chrome session and its cached meter values - nothing else. Your normal Chrome profile, your Cursor account and your other Stream Deck plugins are untouched. It sits behind an explicit confirmation in every action's settings panel, and if anything about the request fails validation, the plugin refuses and keeps the session rather than delete the wrong thing.

How do refunds work for DeckBridge for Cursor?

DeckBridge for Cursor is sold on the Elgato Marketplace, so purchases, receipts and refunds are handled by Elgato under the Marketplace refund policy - request one from your Marketplace account, not by email to us. Unsure whether it fits your setup? Ask us first and we'll tell you straight.