Installation

Before you start

You need OpenCode, a Cursor subscription, the cursor-agent command, and Node.js 20 or newer. Confirm both commands resolve before installing the plugin, then sign in to Cursor:

opencode --version
cursor-agent --version
cursor-agent login

opencode --version tells you which section below to follow.

OpenCode 2.x

opencode plugin add @rama_nigg/open-cursor
opencode service restart

plugin add downloads the package and adds it to plugins in your global opencode.json. OpenCode 2.x loads it and lists the Cursor models itself, so you need no provider block, no installer, and no /connect.

Upgrade with:

opencode plugin update

You can also write the entry by hand:

{
  "plugins": ["@rama_nigg/open-cursor"]
}

Use the bare package name. OpenCode downloads the package on its next start, and the download can take longer than the 5 seconds OpenCode gives plugins to activate. If the first command fails with Location plugins did not finish activating, run it again.

Do not run open-cursor install on OpenCode 2.x. It writes the 1.x plugin file ~/.config/opencode/plugin/cursor-acp.js, which 2.x loads as a second copy. Delete that file if an earlier install left it behind.

See Authentication for the login options and Troubleshooting if no Cursor models appear.

Verify

opencode models | grep cursor-acp

If this prints at least cursor-acp/auto, continue to Quick start.

OpenCode 1.x: install with npm

This is the normal 1.x path on Linux, macOS, and Windows:

npm install -g @rama_nigg/open-cursor
open-cursor install

The installer:

adds the cursor-acp provider to your OpenCode configuration;
installs the plugin entry under the OpenCode plugin directory;
discovers the models exposed by cursor-agent;
installs the OpenAI-compatible provider package used by OpenCode.

It backs up an existing configuration before writing unless you pass --no-backup.

The default configuration lives at:

Linux and macOS: ~/.config/opencode/opencode.json
Windows: %USERPROFILE%\.config\opencode\opencode.json

Pass --config <path> if your configuration lives elsewhere. Then run the Verify check.

OpenCode 1.x: Cursor bridge files

The normal install does not touch .cursor.

Run this from a workspace if you want the optional hook and rule that expose OpenCode context inside Cursor:

open-cursor install --install-cursor-bridge

That writes:

.cursor/hooks.json
.cursor/hooks/opencode-bridge-context.mjs
.cursor/rules/opencode-bridge.mdc

Use --cursor-bridge-scope user to write under ~/.cursor, or both to install the project and user copies. The scope flag implies --install-cursor-bridge.

OpenCode 1.x: shell installer

The shell installer supports Linux and macOS:

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

It prefers the npm package. If npm is unavailable, it falls back to the Go TUI or the shell-only installer path.

OpenCode 1.x: manual configuration

Add this to your OpenCode configuration if you do not want to run the installer:

{
  "plugin": ["@rama_nigg/open-cursor@latest"],
  "provider": {
    "cursor-acp": {
      "name": "Cursor ACP",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://127.0.0.1:32124/v1"
      },
      "models": {
        "cursor-acp/auto": {
          "name": "Auto"
        }
      }
    }
  }
}

Manual configuration does not install the optional Cursor bridge files.

OpenCode 1.x: upgrade

npm update -g @rama_nigg/open-cursor

Restart OpenCode after updating. The running plugin process does not replace itself.

Refresh the model list when Cursor adds or removes models:

open-cursor sync-models

Use open-cursor sync-models --variants --compact if you want grouped thinking and fast variants instead of one long flat list.

Install from source

Use this path when developing the plugin:

git clone https://github.com/Nomadcxx/opencode-cursor.git
cd opencode-cursor
./scripts/install-plugin.sh

See Building from source for the development workflow.

On this page