pi-cursor-sdk

pi-cursor-sdk is an open-source MIT-licensed TypeScript extension created by Mitch Fultz (fitchmultz) that integrates Cursor's @cursor/sdk agent runtime directly into the pi coding agent. Rather than translating Cursor behavior into a generic OpenAI-compatible endpoint, it keeps Cursor's native agent loop intact while adding pi-native features like model discovery, context-window variants, thinking controls, session handling, and a local MCP bridge for pi tools.

What It Is

pi-cursor-sdk is a pi provider extension — a plugin that registers a cursor provider inside pi so users can run Cursor models (Grok, Claude, GPT-5.x, Composer, Gemini, and others) without leaving the pi coding agent environment. It is explicitly not an OpenAI-compatible proxy; it is pi-specific by design, preserving the Cursor SDK local agent loop while making Cursor feel native in pi's UI, model picker, session system, and replay cards.

How the Agent Loop Integration Works

The extension runs Cursor models through @cursor/sdk (pinned to exact version 1.0.32) and seeds each Cursor agent with the current pi session context. Key behaviors include:

• Local-first runtime: Local Cursor SDK agents are the default. Cloud runtime requires explicit opt-in (--cursor-runtime cloud) plus a first-use acknowledgement covering remote execution, fresh context, and Cursor Cloud billing.
• Agent pooling and resume: Within a pi session, one Cursor SDK agent is reused across compatible follow-up turns. Branch-scoped local resume reattaches to recorded agents after a pi restart, with strict matching on session file, branch path, cwd/repo root, model/API/tool-surface pool key, SDK store identity, and compaction generation.
• MCP bridge for pi tools: Active pi tools are exposed to local Cursor agents through a tokenized loopback MCP endpoint using stable MCP v2. Overlapping built-in pi tools (read, bash, write, edit, grep, find, ls) are hidden by default since Cursor already has native equivalents; custom and non-overlapping tools are exposed normally.
• Cursor native tool replay: Recorded Cursor SDK activity (web search, subagent, MCP calls, plan/todo cards) is rendered as display-only pi replay cards without re-running any Cursor-side commands or mutating pi state.

Model Selection and Thinking Controls

The extension registers Cursor models under the cursor/ provider namespace with context-window variants (e.g., cursor/gpt-5.5@1m, cursor/claude-opus-4-8@300k) and thinking-level suffixes (:medium, :high, :xhigh, :max) for models where the Cursor SDK exposes a controllable thinking parameter. Fast/slow virtual aliases (:fast, :slow) are registered for models that expose Cursor's boolean fast parameter. The /model command and --model flag work natively for model switching inside pi.

Setup Path

Installation requires Node.js 24+ and a Cursor SDK API key (not a Cursor Desktop or Agent CLI login):

• Install via pi install npm:pi-cursor-sdk or from GitHub
• Start pi with pi --model cursor/grok-4.6
• Run /login inside pi, choose Use an API key, select Cursor, and paste the key
• Run /cursor-refresh-models after login to refresh the live Cursor model catalog without restarting

A model catalog cache at ~/.pi/agent/cursor-sdk-model-list.json (keyed by API-key fingerprint, never storing the key itself) avoids a live network round-trip on every startup. The TTL defaults to 24 hours and is configurable via PI_CURSOR_SDK_MODEL_CACHE_TTL_MS.

Update: v0.4.0

The latest release is v0.4.0, published on 2026-09-26, targeting official Pi 0.87.1 or later. This release ships the compiled dist/index.js entrypoint (replacing the previous src/index.ts entrypoint), requiring users with custom extension filters to update their filter patterns. The repository shows active development with 335 stars and 71 forks as of the last update, and the fallback model catalog includes Grok 4.6, Composer 2.5, GPT-5.6 Luna/Sol/Terra, Claude Opus 4, Gemini, Kimi, and other models from the reviewed Cursor.models.list() output.

Tradeoffs to Know

• The pi tool bridge is local-only; cloud runtime does not expose pi tools or forward pi environment variables.
• Cursor ambient MCP (from ~/.cursor/mcp.json) is loaded by default via PI_CURSOR_SETTING_SOURCES=all and can slow the first message by up to 10 seconds per unavailable server; the extension shortens the known MCP initialize/listTools timeout to 10 seconds (down from the SDK's 60-second default).
• Output token limits are not exposed by the Cursor SDK, so the extension uses conservative estimates.
• Cloud runtime raw usage is display-only and not counted in pi cost totals, context occupancy, or compaction.
• thinking=no in pi --list-models means pi cannot control the thinking level for that model, not that the model cannot think internally.