# pi-cursor-sdk

> A pi provider extension that runs Cursor models through the local Cursor SDK agent loop inside the pi coding agent, with native model selection, thinking controls, fast/plan modes, and MCP-bridged pi tools.

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.

## Features
- Runs Cursor models through the native @cursor/sdk agent loop inside pi
- Local-first runtime with explicit Cursor Cloud opt-in
- Native pi model picker, /model command, and --model flag support
- Context-window variants (e.g., @1m, @272k, @300k) for supported models
- Thinking-level suffixes (:medium, :high, :xhigh, :max) for models with controllable thinking
- Fast/slow virtual model aliases (:fast, :slow) for models with Cursor fast parameter
- MCP bridge exposing active pi tools to local Cursor agents via loopback MCP endpoint
- Cursor native tool replay cards (web search, subagent, MCP, plan/todo) as display-only
- Branch-scoped local agent resume after pi restart
- Model catalog cache with configurable TTL to avoid startup network round-trips
- Cursor SDK mode switching (agent/plan) via /cursor-mode and --cursor-mode
- HTTP/1.1/SSE transport compatibility mode for VPN/proxy environments
- Image input forwarding from latest user message to Cursor
- Cloud runtime with pull-request controls, managed environment selection, and durable lifecycle
- Fallback model catalog when discovery fails or no API key is present
- Per-session SQLite store isolation for parallel pi sessions
- Configurable MCP tool-call timeout (default 3600s, up from SDK's 60s default)
- Shortened MCP initialize/listTools timeout (default 10s) for fast-fail on unavailable servers
- AGENTS.md/CLAUDE.md deduplication to avoid double-injecting context Cursor already loads
- Bridge diagnostics via PI_CURSOR_PI_TOOL_BRIDGE_DEBUG=1

## Integrations
pi coding agent (official Pi 0.87.1+), @cursor/sdk 1.0.32, Cursor Cloud, MCP (Model Context Protocol) v2, @modelcontextprotocol/server 2.1.0, @modelcontextprotocol/hono 2.0.1, hono 4.13.9, @hono/node-server 2.1.1, Cursor MCP servers (via ~/.cursor/mcp.json), Cursor Agent Skills, npm registry, GitHub

## Platforms
WINDOWS, MACOS, LINUX, WEB, API, DEVELOPER_SDK, CLI

## Pricing
Open Source

## Version
v0.4.0

## Links
- Website: https://github.com/fitchmultz/pi-cursor-sdk
- Documentation: https://github.com/fitchmultz/pi-cursor-sdk/blob/main/README.md
- Repository: https://github.com/fitchmultz/pi-cursor-sdk
- EveryDev.ai: https://www.everydev.ai/tools/pi-cursor-sdk