opencode-cursor-sdk

OpenCode plugin to use your Cursor subscription inside OpenCode, with optional @cursor/sdk tools for cloud and one-shot local agents.

The OAuth provider path (Lane A) uses unofficial Cursor client APIs (gRPC over HTTP/2). Cursor may change these at any time; this project is not affiliated with or endorsed by Cursor. Portions of Lane A are derived from ephraimduncan/opencode-cursor (MIT).

The SDK tools (Lane B) use the official @cursor/sdk package and a Cursor API key.

Linux & macOS (one line):

curl -fsSL https://raw.githubusercontent.com/dontmint/opencode-cursor-sdk/main/scripts/install.sh | bash

With OAuth login in the same step:

curl -fsSL https://raw.githubusercontent.com/dontmint/opencode-cursor-sdk/main/scripts/install.sh | bash -s -- --auth

The curl installer downloads this repo’s install.sh, then runs bunx/npx opencode-cursor-sdk setup to merge the plugin into your OpenCode config (requires Node.js >= 18 and npx or bunx on your PATH).

From npm (after publish):

npx opencode-cursor-sdk setup --global
opencode providers login -p cursor

Or use the install script from a cloned repo:

./scripts/install.sh --global          # uses npx/bunx when published
./scripts/install.sh --local --auth    # dev: build + file:// plugin + OAuth

The setup command is idempotent — it merges the plugin entry and provider.cursor stub without removing your other config.

Options:

Important: If you previously used cursor-acp, that is a different integration (Cursor CLI / agent login). This plugin uses provider cursor with OAuth. The install script removes cursor-acp by default (--no-acp). In OpenCode, pick cursor/composer-2 (or another cursor/* model), not cursor-acp/*.

Add to ~/.config/opencode/opencode.json (or project opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-cursor-sdk"],
  "provider": {
    "cursor": {
      "name": "Cursor"
    }
  }
}

The cursor provider stub is required — OpenCode drops providers that are not in its bundled catalog unless you declare them.

For local development:

{
  "plugin": ["file:///absolute/path/to/opencode-cursor-sdk/dist/index.js"]
}

Run npm run build first.

opencode providers login -p cursor

Choose Login with Cursor (subscription). Tokens are stored under ~/.local/share/opencode/auth.json and refreshed automatically.

Start OpenCode and pick a cursor/... model. The plugin starts a local OpenAI-compatible proxy on port 65535 when OpenCode loads the plugin.

Troubleshooting

• Unknown provider "cursor" — the plugin failed to load. Rebuild (bun run build or npm run build), confirm opencode.json points at dist/index.js, then restart OpenCode. Remove conflicting ~/.config/opencode/plugin/cursor-acp.js if present.
• Cannot connect to API / port 65535 — OpenCode must be running so the plugin can bind the proxy. If a previous session crashed, free the port: lsof -ti:65535 | xargs kill -9, then restart OpenCode.
• config.providers / provider.list failed on startup — usually port 65535 still held by a zombie OpenCode process; free it as above, run bun run build, and restart.
• Use opencode providers login -p cursor (not only auth login; both are aliases in recent OpenCode versions).
• Connect error unauthenticated with a token that looks valid in auth list — your ~/.local/share/opencode/auth.json may contain placeholder tokens (e.g. from an old smoke test). Run opencode providers login -p cursor again to replace them with real OAuth tokens.
• Connect error internal: Blob not found when resuming a session — usually stale Cursor conversation state without local blob data. Rebuild the plugin, restart OpenCode, and send your next message again (state is reset automatically). Conversation blobs are stored under ~/.local/share/opencode/cursor-sdk-conversations/.

Verify models are listed:

opencode models cursor

You should see entries like cursor/composer-2. After OAuth login, refresh the full model list from your Cursor account:

npx opencode-cursor-sdk sync-models
# or from this repo:
bun bin/setup.js sync-models

OpenCode also syncs models automatically when the plugin loads (restart OpenCode after login).

If you get Provider not found: cursor, re-run setup (it adds npm, api, and placeholder models required by OpenCode):

./scripts/install.sh --local --no-acp

Install @cursor/sdk next to the plugin (dev dependency is enough for the Node bridge subprocess):

export CURSOR_API_KEY="cursor_..."   # Dashboard → Integrations

SDK usage bills to your Cursor plan the same way as other SDK runs.

OpenCode  →  /v1/chat/completions  →  Bun proxy
                                      →  Node h2-bridge.mjs
                                      →  api2.cursor.sh (OAuth)

OpenCode tools  →  cursor_sdk_*  →  Node sdk/bridge.mjs  →  @cursor/sdk

1. OAuth — PKCE browser login.
2. Model discovery — Cursor gRPC GetUsableModels.
3. Local proxy — OpenAI chat completions → Cursor AgentService; native Cursor tools are rejected so OpenCode keeps the tool loop.
4. SDK bridge — JSON-RPC over stdio to a Node child (avoids loading sqlite3 native bindings in Bun).

npm install
npm run build
npm test

Optional SDK bridge check (requires CURSOR_API_KEY):

CURSOR_API_KEY=cursor_... npm test

• OpenCode
• Bun (OpenCode runtime)
• Node.js >= 18 (HTTP/2 bridge + SDK bridge)
• Active Cursor subscription (Lane A)
• CURSOR_API_KEY for Lane B tools only

MIT — see LICENSE.