Cursor

The Cursor provider runs Cursor's agent on the relay's machine, through the Cursor Agent SDK. OAR starts one worker process per conversation. The agent works in the conversation's working folder, with your Cursor account's models. Unlike Claude, it does not use a login on the machine: you give OAR a Cursor API key.

This page covers what is particular to Cursor. The chat, the queue and the file browser work as for every provider; see Providers at a glance for how Cursor compares.

What you need #

• A Cursor API key. You paste it into OAR once; see Switching it on.
• Nothing to install. Cursor needs no CLI and no Cursor app on the machine, so the Cursor sub-tab has no CLI row.

Where things live:

By default the state folders are under cursor-agents in the relay's data folder: ~/.oar/data/cursor-agents (%APPDATA%\oar\data\cursor-agents on Windows) on a global install, server/data/cursor-agents in a git checkout. Added in 0.9.14 Before 0.9.14 a global install kept them inside the package folder, which an update replaces, so a conversation could lose its agent; a conversation whose folder is still there keeps using it. CURSOR_AGENT_STORE_DIR moves them; see Environment variables.

Switching it on #

Open Settings → Providers → Cursor. The panel is headed Cursor SDK.

The status line under the fields says where you are:

What saving does:

• Model discovery. When Cursor is switched on and you save a new key, or change the model, or switch it on again, OAR asks Cursor for the models your key can use, and for each model's reasoning options. The request gives up after 20 seconds. A failure shows as a warning in the notice, for example Cursor model discovery failed: …. Until a discovery succeeds, the list holds only the default model.
• Changing the key. Saving a new key clears the discovered models and, if Cursor is on, runs discovery again. When a key was already saved, the relay also stops every Cursor worker, including one in the middle of a turn, so save a new key between turns. The workers start again with the new key on the next message.
• Removing the key is refused while any Cursor conversation has sent a message or has messages queued: Cannot remove Cursor API key while N active Cursor conversation(s) still exist. Disable Cursor for new conversations instead. So no running turn is affected by a removal. Switch Cursor off instead. When the removal goes through, conversations that have not sent a message yet move back to Copilot. Switching Cursor off does not move them.

Then start a conversation as usual: in New Chat, pick the provider Cursor SDK. See Starting a conversation.

Models and effort #

Where the list comes from. From Cursor itself, through your key, at the moments listed above. 🤗 Select Models → Cursor SDK chooses which of them the composer offers; 💾 Save enabled models keeps the choice, and Refresh runs discovery again. With no choice made, all discovered models are offered. The model in Cursor model ID is always offered.

Per message. A conversation can change model and effort from one message to the next; Cursor model IDs are used as Cursor spells them. An ID that is not among the models offered to you (the enabled ones, plus Cursor model ID and the conversation's own model) is refused with Cursor model "…" is not available.

Effort. The effort choices come from the model, as it lists them. OAR knows these levels: none, low, medium, high, xhigh and max. Cursor's extra-high appears as xhigh. A level OAR does not know is not offered.

• none is always in the list. If the model can switch reasoning off, none does that. If it cannot, the composer shows the entry as default, and the model runs as it normally does.
• A model that lists no effort has only none, shown as default.
• On a model that has a thinking switch, choosing a level turns thinking on and none turns it off.

Sub-agents on other models. Cursor's built-in sub-agent menu offers only a couple of models. OAR therefore declares one sub-agent per model you have enabled in Select Models, so the agent can hand a task to, say, a Grok or GPT model. Names use dashes (grok-4.5 becomes grok-4-5). A sub-agent runs its model's default variant: it cannot be given an effort. Changing the selection takes effect on the next message.

How OAR's features work on Cursor #

Cursor's own project rules, sub-agent files and MCP servers in the working folder's .cursor folder are not loaded. OAR defines the agent's tools and sub-agents itself.

A long-idle agent #

A Cursor agent that has not been used for 30 minutes is closed and reopened on the next message, because its sign-in goes stale after a few idle hours. You do not see this. If the sign-in has gone stale anyway, OAR rebuilds the agent and sends the message again, up to twice, and adds the activity line Cursor session re-authenticated; retrying this message on a fresh agent handle. A third failure ends the turn with the sign-in message in If it does not work.

Usage #

Cursor turns have no usage line under the reply. 📊 Check Usage has a Cursor card. While Cursor is off it reads Cursor is not enabled in provider settings. Its figures come from two sources, and the card says which one it used.

Spend from OAR, an estimate. After each turn OAR reads the agent's billed spend from Cursor and books the increase to the current billing cycle. It files each turn under the pool of the model that ran it:

Matching ignores case, and the router names are checked first.

Cursor does not tell the SDK what your plan includes. You enter that:

The meters measure the raw model cost against your allowance. The card also lists what Cursor actually charged, which is often zero for plan-included use. All of these figures are estimates. A cost that Cursor reports late is booked with the turn that sees it. Cursor's own Spending dashboard is the authoritative source, and the card links to it.

Live plan bars, from the dashboard. With a dashboard session token, the card adds Plan usage (total), Auto + Composer and API bars read live from Cursor's dashboard, the plan name, the included and on-demand spend, and the cycle's real dates. The local pool meters then move back to secondary. The token is a session cookie, not the API key, and the API key cannot read these figures.

OAR looks for a token in this order:

1. The one you saved.
2. CURSOR_SESSION_TOKEN in the relay's environment, for hosts with no Cursor app.
3. The login of the Cursor app on the relay's machine, read from its local state with no setup.

The status line under the field names the source in use. The token stays on the relay and is never sent to a browser. If Cursor does not accept the token, the card falls back to the estimates and says which source was rejected, or that no token was found.

An agent can read the same figures with relay_tool's usage action.

Environment variables #

Set these in the environment the relay starts in.

The API key cannot be set this way: the relay passes its workers the key from the panel and ignores a CURSOR_API_KEY in its own environment.

Limits #

Beyond the gaps in the table above (no steering, no task panel, no compaction setting, one sub-agent level):

• Question cards depend on the agent calling ask_user.
• Spend and allowances are estimates. Only the dashboard bars come from Cursor.
• A usage limit on your Cursor plan does not pause the conversation. The turn fails like any failed turn, and you send the message again.

If it does not work #