DOCSEARCHbyAlgolia
Submit Docs

open-cursor

repository·main·Indexed 20 days ago

https://github.com/nomadcxx/opencode-cursor

A translation layer and bridge that enables OpenCode users to leverage models from their Cursor subscription. It connects OpenCode to the cursor-agent backend, translating prompts, streaming responses, thinking processes, and tool calls into an OpenAI-compatible format via a local proxy.

Tokens
36.5K
Snippets
133
Records
207
Agent score
69%

What's inside open-cursor

  1. Overview of open-cursor

    main
    open-cursor is a bridge that connects OpenCode to the models available through your Cursor subscription. It handles the translation of prompts, streaming responses, thinking processes, and tool calls between the OpenCode interface and the cursor-agent backend.

  3. Compare Cursor-to-OpenCode integration approaches

    main

    When choosing a project to connect Cursor models to OpenCode, evaluate them based on their protocol, authentication method, and tool-execution boundaries. The main approaches include:

    • open-cursor (This project): Wraps cursor-agent with an optional official Cursor SDK fallback. Uses existing CLI login or Cursor API key. It maintains the supported CLI path by translating a process stream into an OpenCode provider.
    • stablekernel/opencode-cursor: Uses the official @cursor/sdk provider with a Cursor API key. Offers direct SDK integration, but note that Cursor tools may run outside OpenCode permissions unless sandboxed.
    • cursor-opencode-provider: Uses Cursor Connect-RPC and protobuf. Supports Browser OAuth or Cursor API key. Provides rich native protocol mapping for better compatibility when Cursor protocols change.
    • yet-another-opencode-cursor-auth: An unofficial Cursor service interface using OAuth. Supports dynamic models and tool calls, but is experimental and carries account/compatibility risks.
    • opencode-cursor-auth: A local cursor-agent-backed OpenAI-compatible service using Cursor subscription and CLI login. Tool calling is experimental and lacks thinking/usage accounting.
    • cursor-opencode-auth: A standalone OpenAI-compatible proxy using a Cursor CLI token from the macOS Keychain. Works with any compatible client but requires macOS and a running proxy.

  4. Explore the docs-site project structure

    main

    The docs-site is a Next.js application using Fumadocs with Static Export configured. Key files and routes include:

    • lib/source.ts: Contains the content source adapter code. Use the loader() interface to access your content.
    • lib/layout.shared.tsx: Contains shared layout options.
    • app/(home): Route group for the landing page and other general pages.
    • app/docs: The main documentation layout and pages.
    • app/api/search/route.ts: The Route Handler responsible for search functionality.

  5. How Session Resume works and what triggers a new chat

    main

    Session resume uses an in-memory map to link an OpenCode conversation anchor to a cursor-agent chat ID.

    The conversation anchor consists of:

    • The workspace
    • The concrete Cursor model
    • A hash of the first real user message

    When a new chat is started (cache invalidation):

    • Changing the workspace, model, or the opening message.
    • Changing tool definitions (including the Task subagent list).
    • Metadata prompts (like title generation) are excluded from the anchor and do not affect reuse.

    On subsequent turns, the plugin verifies the known message prefix and a fingerprint of available tool schemas before applying the --resume flag.

  6. Understand the OpenCode Skills Bridge execution flow

    main

    The OpenCode Skills Bridge enables bidirectional tool flow between the Cursor agent and OpenCode skills. When a user requests a skill (e.g., brainstorm), the following lifecycle occurs:

    1. Discovery: The cursor-acp provider discovers the tool from OpenCode.
    2. Transformation: The tool is converted to an OpenAI-compatible format (e.g., opencode_brainstorm).
    3. Exposure: The tool list is sent to the Cursor agent.
    4. Invocation: The Cursor model calls the tool (e.g., opencode_brainstorm({ topic: "..." })).
    5. Routing: The cursor-acp interceptor routes the tool call to OpenCode via an HTTP callback.
    6. Execution: OpenCode executes the skill.
    7. Response: The result is streamed back through cursor-acp to the Cursor model.

    This allows OpenCode skills to appear as native tools within the Cursor interface.

    User Prompt: "I want to build a Pong game in Go. Use the brainstorm skill to generate design ideas."

Execution Flow:
1. OpenCode loads cursor-acp provider
2. Provider discovers `brainstorm` tool from OpenCode
3. Converts to OpenAI format: `opencode_brainstorm`
4. Sends to cursor-agent with tools list
5. Cursor model calls `opencode_brainstorm({ topic: "Pong game in Go" })`
6. cursor-agent streams tool call event
7. cursor-acp intercepts, routes to OpenCode via HTTP callback
8. OpenCode executes `brainstorm` skill
9. Result streams back through cursor-acp
10. Cursor model receives result, continues conversation

  7. Understand the Model and Agent integration planes

    main

    When integrating Cursor with other coding harnesses, the integration falls into one of two conceptual planes:

    1. Model plane: The harness communicates with a model API and manages tools, permissions, and the execution loop. In this mode, the bridge acts as a proxy for the model. This approach is subject to 'tool-ownership' challenges where the bridge must continuously extract tool calls from Cursor's stream.
    2. Agent plane: The harness dispatches Cursor's composer as a subagent. The harness runs its own loop and receives results back. In this mode, Cursor owns the tools, which simplifies the integration as the harness treats Cursor as a black-box agent.

  8. How the OpenCode Skills Bridge works

    main

    The OpenCode Skills Bridge enables bidirectional tool flow between OpenCode and Cursor. While the current state is one-directional (Cursor tools $\rightarrow$ OpenCode), the goal is to allow Cursor models to invoke OpenCode's registered skills (e.g., brainstorm, write_plan) and MCP tools.

    Architecture Components

    • OpenCode Skills Registry: Stores available OpenCode skills.
    • cursor-acp Plugin: Acts as a bridge containing a Tool Registry + Router and an HTTP Proxy (typically on port 32124).
    • Cursor Agent: Handles tool calls via streaming and receives model responses with results.

    The Tool Invocation Pattern

    Because the OpenCode SDK does not currently expose a direct tool.invoke() method, the bridge uses an HTTP callback mechanism:

    1. The cursor-acp plugin exposes an HTTP endpoint for tool execution.
    2. The Provider detects a tool call from the Cursor agent.
    3. The Provider calls the plugin's HTTP endpoint to trigger execution.
    4. The plugin executes the tool via OpenCode's internal mechanism and returns the result.

  9. Understand the Ownership Boundary and Tool Execution

    main

    There is a distinction between tool execution ownership:

    1. OpenCode Ownership: In the default tool loop, OpenCode owns the execution of intercepted tools.
    2. Cursor Ownership: Cursor's internal process can still execute Cursor-native tools within its own agent flow.

    Important Note on File Mutations: The plugin can translate events that reach the boundary, but it cannot undo file mutations already performed by Cursor's child process. While a strict JSON write bridge is used for complete-file writes to reduce risk, it is a steering mechanism and not a complete sandbox.

  10. Understand model pricing and costs

    main

    OpenCode displays usage costs by attaching known prices from the package pricing table during the sync-models command.

    • Pricing updates: Pricing is managed independently of the plugin. Always verify costs against Cursor's official pricing documentation for cost-sensitive decisions.
    • Unknown prices: If a price is unknown, it will simply be absent from the display; the plugin does not estimate or invent values.

  11. How OpenCode and Cursor interact via the local proxy

    main

    OpenCode presents Cursor as an OpenAI-compatible provider. To bridge the gap between OpenCode's OpenAI-compatible chat requests and Cursor's specific process/stream protocol, a local proxy runs on 127.0.0.1:32124.

    This proxy acts as a translation layer that converts Cursor's newline-delimited stream events into OpenAI-compatible responses (including assistant text, thinking, usage, errors, and tool calls).

    OpenCode
  │  OpenAI-compatible chat request
  ▼
local proxy on 127.0.0.1:32124
  │
  ├─ cursor-agent, default
  └─ Cursor SDK runner, optional fallback
       │
       ▼
    Cursor API
       │  stream-json events
       ▼
provider boundary
  ├─ assistant text and thinking → SSE
  └─ tool calls → OpenCode tool calls

  12. Design System Overview for open-cursor documentation

    main

    The open-cursor documentation uses a locked design system characterized by a modern-minimal, technical documentation register. The system is organized into three macrostructure families:

    • Documentation home (Index-First): Opens with a short identity block and prioritizes page groups as the primary content.
    • Application shell (Workbench-informed): Features persistent navigation, search, page tools, and a table of contents that function like an instrument panel.
    • Content pages (Long Document): Uses a single readable column with direct section heads, inline code, tables, and restrained page tools.

    Developers should extend the existing system when necessary rather than picking new themes per page.