Pi Cursor Bridge

⭐ If Cursor Bridge helps you, please consider giving it a Star on GitHub—it helps others discover the project.

_{Compatibility policy: Cursor Bridge maintains only the latest Cursor release; previous Cursor releases are not actively supported. If you need a historical Cursor version, first open the Cursor Bridge compatibility and update history and switch precisely to its matching archived release when one is listed. Archived releases receive no maintenance. If no historical release meets your needs, use Fork in the top-right corner and maintain the required adaptation in your own fork.}

Cursor Bridge + Grok Build Supervisor

简体中文 · Changelog · Releases · Issues

Release Stars Node.js MCP License

[!WARNING] Windows only: Cursor Bridge and Grok Build Supervisor currently support Windows only. macOS and Linux are not supported or covered by end-to-end acceptance.

Two independently installable MCP plugins for Codex, Claude Code, Grok Build, and Pi. Install only the bridge you need.

Give the coding client you already use access to Cursor and Grok Build

Keep using Codex (recommended), Claude Code, or Pi as your normal coding client. The plugins are independent: install Cursor Bridge to let that client use Cursor, install Grok Build Supervisor to let it coordinate Grok Build, or install both to combine those capabilities in one conversation.

Codex (recommended) / Claude Code / Pi
      your existing coding client
              │
   plugins add coordination abilities
          ┌───┴──────────────┐
          ▼                  ▼
    Cursor Bridge     Grok Build Supervisor
   CCE + cursor_do       supervised Grok Build

• Start with cursor_context_engine for compact, source-anchored project understanding.
• Use the now first-class cursor_do path for a bounded Cursor Agent task when delegated execution saves time; your current client still reviews the real diff and tests.
• Turn on /grok_execute on when Grok Build should execute while your current client plans, monitors, handles questions, and verifies the result.

This repository is not a separate orchestrator. The plugins add these capabilities to the client you already use, so install only what you need.

Grok Build Supervisor (New)

Let Codex, Claude Code, or Pi plan and review the work while automatically coordinating Grok Build to execute tasks, track progress, and verify results.

It is installed and updated independently from Cursor Bridge.

Read the introduction, installation, and usage guide →

Cursor Bridge

Let Codex, Claude Code, Grok Build, or Pi use Cursor CCE to understand the project, locate the right code, and trace relationships automatically; when needed, the optional cursor_do feature can execute clearly scoped tasks.

[!IMPORTANT] One-time Windows migration: If the installed Cursor Bridge version is 5.3.6 or earlier, save your work before the first upgrade to 5.4.0 or any later release, then follow Update an existing installation to clean up old-cache processes once. Later updates use the normal flow.

[!NOTE] See Compatibility and update history and the latest release for the current pairing and its evidence boundary.

CCE and cursor_do accept optional request_context, for example {"sender":"model","source":"mixed"}. sender declares who directly sends the request (user/model/unknown); source distinguishes user requirements from model additions (user/model/mixed/unknown). Separate both in mixed prompt text. Omitted values remain unknown, are not inferred from the selected model, and never grant extra permission. Task status reports the declaration for that turn.

Live-tested environment: Windows 11 + Cursor 3.19.7, identified from the installed executable's product and file versions. A fresh Codex host reused one undegraded persistent supervised Agents Window and passed workspace binding, source-anchored CCE in minimal, isolated FIFO cursor_do in normal and minimal with verified Claude Fable 5.1/high selection, and restored and persisted normal. Parallel and persistent-session paths retain regression coverage but were not live-rechecked in this acceptance. Requires Node.js 18+, Cursor installed and signed in, and a local project Cursor can open. The legacy IDE/workbench target was not exposed, and macOS has not yet been live-tested.

What is CCE?

Cursor Context Engine (CCE) exposes Cursor's existing project index and Agent search capabilities to Codex, Claude Code, Grok Build, and Pi through MCP.

Ask a project question once. Cursor chooses the semantic retrieval, exact search, source reading, reference tracing, or Agent exploration it needs. Cursor Bridge returns compact, source-anchored path:line evidence with relevance notes instead of dumping the entire search process into the main Agent's context.

That means fewer blind directory guesses, fewer repeated grep calls, and less context-window waste.

Cursor Bridge does not inspect or manage your Cursor subscription. The models, quotas, and BYOK options available to your signed-in Cursor remain part of your own Cursor setup.

Quick start

1. Choose your client and install what you need

The commands are grouped by the client you already use. Cursor Bridge and Grok Build Supervisor are independent: install either one, or both.

Codex (recommended)

codex plugin marketplace add Vanyangyang/cursor-bridge --ref main
codex plugin add cursor-bridge@vanyangyang
# Optional: add the Supervisor for the combined Cursor + Grok Build workflow
codex plugin add grok-build-supervisor@vanyangyang

Claude Code

claude plugin marketplace add Vanyangyang/cursor-bridge
claude plugin install cursor-bridge@vanyangyang
# Optional: add the Supervisor for the combined Cursor + Grok Build workflow
claude plugin install grok-build-supervisor@vanyangyang

Grok Build

grok plugin marketplace add Vanyangyang/cursor-bridge
grok plugin install Vanyangyang/cursor-bridge --trust
grok plugin enable cursor-bridge

grok plugin install Vanyangyang/cursor-bridge --trust also works without adding the marketplace first.

Pi

pi install npm:pi-cursor-bridge
# Optional: add the Supervisor for the combined Cursor + Grok Build workflow
pi install npm:pi-grok-build-supervisor

2. Restart or reload your client

Restart Codex and start a new task, restart Claude Code or run /reload-plugins, reload Grok through /plugins or start a new Grok session, or restart Pi. Grok keeps plugins disabled until you run grok plugin enable cursor-bridge; --trust allows the plugin's MCP server and hooks to run.

3. Initialize the plugin you installed

If you installed Cursor Bridge, Pi automatically binds it to the directory where Pi was started. Other hosts can initialize or switch the project in natural language; Pi can use the same sentence when you intentionally want a different project:

Initialize CCE workspace to C:\absolute\path\to\project

Initialization is persistent. Repeat the sentence with another absolute path whenever you want to switch projects.

If you installed Grok Build Supervisor, initialize once ($grok-build-supervisor init in Codex), then select Enable Grok Execution in the project where Grok should work. Disable Grok Execution returns the host to normal execution without closing the terminal. Neither control needs an extra argument. See the Grok guide for other hosts and compatibility commands.

4. Start with a real task

With Cursor Bridge, ask the real project question:

Who owns this state, and what is the complete path from save loading to runtime use and save write-back?

With Grok Build Supervisor enabled, send your normal implementation task; the current client handles planning and verification while Grok Build executes.

[!TIP] Recommended on Windows 11: minimal runtime

After initialization, say “Switch CCE to minimal mode.” The real Cursor process, project index, Agent DOM, and task queue keep running in the background while top-level windows stay hidden. You can use Cursor as the capability behind the plugin without visible interruption; cursor_context_engine and cursor_do remain available.

Trade-off: while minimal mode is active, manually opening Cursor reuses the guarded single-instance process and remains hidden. Before you need the Cursor UI again, say “Switch CCE to normal mode.”

Compatibility

See Compatibility and update history and the latest release for the current pairing, evidence boundary, and archived installation instructions. If Agents Window is not available, CCE uses the IDE when Cursor exposes that surface. Running FIFO tasks publish an Agent ID when the current editor exposes one; cursor_task_control cancel then stops that exact task. If no ID is published, Bridge does not guess-click Stop.

Supported hosts: Codex, Claude Code, Grok Build, and Pi. After installing on Grok, run grok plugin enable cursor-bridge, then /plugins and r, or start a new session.

Use CCE and cursor_do

• Start with project understanding: cursor_context_engine follows ownership, call chains, data flow, registrations, and cross-module relationships, then returns compact source anchors, coverage, gaps, and confidence.
• Move to bounded execution with cursor_do: send a clearly scoped Cursor Agent task and receive a stable task ID for collection and recovery. cursor_do is optional, but no longer hidden as an edge feature: use it whenever a bounded Cursor pass is the efficient execution path. The primary Agent remains responsible for reviewing the result, real workspace changes, and verification evidence.
• Keep the model you chose: say “Use GPT-5.6 Terra with max effort for CCE” or “Use GPT-5.6 Sol with high effort for cursor_do.” cursor_model stores independent defaults for CCE and cursor_do across host tasks and restarts until you explicitly change or reset them. Before every prompt, Bridge applies and verifies the selection; it fails before sending instead of silently falling back to Auto.

Full MCP tool reference

[!WARNING] Cursor is an Agent, not a filesystem sandbox. CCE strongly prompts read-only investigation, but prompts and allowed paths are not OS-level isolation. Verify consequential anchors and workspace changes.

Update Cursor Bridge

Cursor Bridge 5.4.0 and later use the normal update commands below. If the currently installed version is 5.3.6 or earlier, complete the one-time Windows migration first, then return to these commands.

Codex:

codex plugin marketplace upgrade vanyangyang
codex plugin add cursor-bridge@vanyangyang

Claude Code:

claude plugin marketplace update vanyangyang
claude plugin update cursor-bridge@vanyangyang

Grok Build:

grok plugin marketplace update cursor-bridge
grok plugin update cursor-bridge

Pi:

pi update npm:pi-cursor-bridge

After updating, start a new Codex task, restart Claude Code or run /reload-plugins, reload Grok through /plugins or start a new Grok session, or restart Pi. An already open task does not hot-load new MCP, Skill, or command code.

If Codex reports marketplace 'vanyangyang' is not configured as a Git marketplace, run codex plugin marketplace add Vanyangyang/cursor-bridge --ref main once, then retry the Codex commands above.

One-time Windows migration from Cursor Bridge 5.3.6 or earlier

[!WARNING] Only the first Windows upgrade from Cursor Bridge 5.3.6 or earlier needs this cleanup. Old plugin processes can keep a versioned cache directory open and block replacement. Do not change ACLs or delete the plugin cache.

[!TIP] Recommended — copy this to your local coding Agent: “I saved my work. First check the installed Cursor Bridge version. Only if it is 5.3.6 or earlier, inspect processes whose command lines load cursor-lifecycle-supervisor.mjs or dist/cursor-bridge.mjs from the host's versioned plugin cache. Treat every instance under %LOCALAPPDATA%\cursor-bridge\lifecycle\runtime\ as the new persistent runtime and do not stop it. After verifying the exact old-cache path and ownership, stop only those old-cache processes without asking again; do not mass-stop Node or PowerShell, change ACLs, delete caches, or touch unrelated processes. The current task's old Cursor Bridge MCP may disconnect when its old adapter stops; that is expected. Then update Cursor Bridge to the latest version using the current host's normal marketplace command, reload the host, and report the installed version, marketplace source, and any old-cache process that remains.”

After this one-time migration, later updates do not need special process cleanup.

CCE_SEARCH_RESULT
intent: <normalized intent>
coverage: <focused|extended> | <why this depth was sufficient>
evidence:
- path/to/file.ts:42-67 | symbolOrAnchor | verified relevance or relationship | reference
gaps: none
confidence: high

Codex / Claude Code / Grok Build / Pi
        │ MCP
        ▼
Cursor Bridge adapter(s)
        │ singleton IPC
        ▼
Shared lifecycle supervisor
        │ ensure / CDP :9223
        ▼
Cursor Agent + project index

git clone https://github.com/Vanyangyang/cursor-bridge.git
cd cursor-bridge
npm install
npm run build

{
  "mcpServers": {
    "cursor-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/cursor-bridge/server.mjs"]
    }
  }
}

Friends

• LINUX DO — A new kind of ideal community.

License

MIT

Star History

Cursor Bridge Star History