@rahularya01/pi-cursor

A Pi Coding Agent provider for Cursor models. It adds provider cursor, multi-source authentication resolution (macOS Keychain, Cursor IDE, WSL host, environment variables, or PKCE browser OAuth), native Connect/protobuf streaming over HTTP/2, model discovery, thinking effort routing, and visual TUI usage diagnostics—without invoking the Cursor CLI for day-to-day chat.

Unofficial integration. This project is not affiliated with or endorsed by Cursor / Anysphere. It uses reverse-engineered Wire protocol details shared by community clients (see attributions). Use it only with an account you are authorized to access, and review its source before granting OAuth permissions. Cursor may change wire protocol endpoints or formats at any time.

Requirements

• Pi Coding Agent and Pi AI version 0.80.0 or later
• A Cursor account with model access (or Cursor CLI / Cursor IDE logged in on your machine)
• Node.js version 22.0.0 or later (for native HTTP/2 Connect streaming and SQLite credential resolution)

Install

Install from npm:

pi install npm:@rahularya01/pi-cursor

Or install the latest repository version:

pi install git:github.com/Rahularya01/pi-cursor

Restart Pi (or run /reload) after installation. To update the package later, run pi update npm:@rahularya01/pi-cursor.

Quick start

1. If you are already logged in to Cursor CLI or the Cursor app on your machine, pi-cursor auto-detects your credentials. Otherwise, start Pi and run /login cursor to sign in via browser.

2. Select a model, for example:

   /model cursor/composer-2
   

3. Start working. Use /cursor.doctor to verify diagnostics and active authentication source.

Authentication and resolution cascade

pi-cursor automatically resolves credentials using a 4-tier cascade:

1. CURSOR_ACCESS_TOKEN environment variable
2. Cursor CLI credentials in macOS Keychain (cursor-access-token / cursor-refresh-token)
3. Cursor IDE local state DB (globalStorage/state.vscdb on macOS, Windows, Linux, or WSL)
4. Pi OAuth credentials store (~/.pi/agent/auth.json via /login cursor)

Automatic CLI & IDE login detection

If you are logged into the Cursor desktop app or Cursor CLI (cursor / agent), pi-cursor automatically extracts your session credentials so you can start chatting immediately without manual browser login.

On WSL (Windows Subsystem for Linux), pi-cursor automatically scans Windows host user profiles (/mnt/c/Users/*/AppData/...) to detect and reuse your Windows Cursor app login.

To opt out of Keychain / IDE / WSL credential reuse (OAuth or CURSOR_ACCESS_TOKEN only):

export PI_CURSOR_SYSTEM_CREDENTIALS=0

Deep-link PKCE browser login

When no local credentials exist, running /login cursor initiates browser sign-in:

1. /login cursor opens https://cursor.com/loginDeepControl?...
2. Pi polls https://api2.cursor.sh/auth/poll until authentication completes.
3. Access and refresh tokens are stored in Pi's auth store (~/.pi/agent/auth.json).
4. Tokens are automatically refreshed via https://api2.cursor.sh/auth/exchange_user_api_key.

Use /cursor.doctor to inspect which source is active (tokenSource=cli_keychain, tokenSource=ide_vscdb, tokenSource=pi_oauth, tokenSource=env).

Commands

Command	Description
/login cursor	Sign in to Cursor via browser PKCE and refresh the live model catalog.
/model cursor/<id>	Choose a registered Cursor model.
/cursor.models	List active runtime models, context windows, and effort capabilities.
/cursor.models all	Include tab/chat internal model variants normally hidden from the picker.
/cursor.usage	Display visual TUI usage dashboard (included/auto/API quota bars, reset dates, on-demand spend).
/cursor.doctor	Show sanitized provider diagnostics, active token source, endpoint, and last error.

Models and reasoning effort routing

pi-cursor discovers live account models via GetUsableModels and parameterized metadata. Reasoning effort levels (off, minimal, low, medium, high, xhigh, max) are mapped directly to Cursor's runtime model variants or reasoning parameters.

Public model ID	Context	Thinking	Description / Routing
cursor/composer-2	200,000	Yes	Cursor's agentic model with fast reasoning effort options.
cursor/composer-1.5	200,000	Yes	Fast agent model optimized for code edit turns.
cursor/claude-sonnet-5	200,000	Yes	Anthropic Claude Sonnet via Cursor infrastructure.
cursor/gpt-5.5	200,000	Yes	OpenAI flagship model with parameterized reasoning levels.
cursor/grok-4.5	200,000	Yes	xAI Grok model via Cursor infrastructure.

To restrict which models Pi displays, configure ~/.pi/agent/settings.json:

{
  "enabledModels": ["cursor/composer-2", "cursor/claude-sonnet-5", "cursor/gpt-5.5"]
}

Usage quota and visual TUI dashboard

Running /cursor.usage displays a formatted terminal interface showing your current billing cycle, progress bars for included plan quota, auto/API usage, reset dates, and on-demand spend:

Usage • Pro                                           Resets 5 Aug
Monthly plan and on-demand usage

Category        Current          Usage
Included        13% used         ███░░░░░░░░░░░░░░░░░
  Auto          12% used         ███░░░░░░░░░░░░░░░░░
  API           14% used         ███░░░░░░░░░░░░░░░░░
On-Demand       Disabled
------------------------------------------------------------
On-demand usage is off

View in dashboard: cursor.com/dashboard?tab=usage

Usage statistics are fetched directly from Cursor's native Connect period usage endpoint (POST https://api2.cursor.sh/aiserver.v1.DashboardService/GetCurrentPeriodUsage) using your active access token, with optional fallback to CURSOR_USAGE_SESSION_TOKEN.

Architecture & Wire Protocol

Pi Coding Agent  →  streamSimple (cursor-native)
                      → h2-bridge.mjs (Node.js HTTP/2 child process)
                      → agent.v1.AgentService/Run (Connect + Protobuf over HTTP/2)

• Transport: Native Connect/protobuf streaming over HTTP/2 via h2-bridge.mjs.
• Context-Mode Normalization: Side-channel user messages (such as context-mode routing or post-compaction <session_state> blocks) are safely normalized into the system prompt so Cursor models stay focused on your primary task.
• Cross-Platform: Tested and fully compatible with macOS, Linux, Windows, and WSL.

Configuration

Variable	Purpose
PI_CURSOR_AGENT_URL / CURSOR_AGENT_URL	Override agent base URL (default: https://agentn.us.api5.cursor.sh).
CURSOR_ACCESS_TOKEN	Static access token override.
PI_CURSOR_CLIENT_VERSION	Pin x-cursor-client-version header sent by the HTTP/2 bridge.
PI_CURSOR_SYSTEM_CREDENTIALS	0/false to disable Keychain/IDE credential reuse (default: allow).
PI_CURSOR_RAW_MODELS	Disable effort-suffix model collapse.
PI_CURSOR_PROVIDER_DEBUG	Enable verbose JSONL debug logging.
PI_CURSOR_LIFECYCLE_LOG	Always-on compact lifecycle log path (default: $TMPDIR/pi-cursor-lifecycle.jsonl).
CURSOR_USAGE_SESSION_TOKEN	Optional WorkosCursorSessionToken fallback cookie for /cursor.usage.
PI_OFFLINE	Skip live model discovery on startup.
PI_CURSOR_STREAM_IDLE_TIMEOUT_MS	Silence safety net: ms with no upstream progress of any kind before recover/retry/error. Default 120000 (2 min); 0 disables (turns run unbounded). Any server signal resets it and it is paused during tool execution, so long reasoning/tools are unaffected — it only fires on a genuine park.
PI_CURSOR_RESUME_IDLE_TIMEOUT_MS	Same silence safety net after tool-result resume. Default 120000 (2 min); 0 disables.
PI_CURSOR_STREAM_IDLE_MAX_RETRIES	Auto-recovery attempts after a silence timeout before erroring (skipped once any text/thinking was streamed, to avoid duplicate output). Default 2; 0 disables.
PI_CURSOR_ACTIVE_BRIDGE_TTL_MS	How long a mid-tool bridge stays parked waiting for tool results (default: 1 hour).
PI_CURSOR_H2_CONNECT_TIMEOUT_MS	h2-bridge initial connect kill (default: 30000; 0 disables).
PI_CURSOR_H2_IDLE_TIMEOUT_MS	h2-bridge activity idle kill. Default 0 (disabled). Parent heartbeats reset it when enabled.
PI_CURSOR_MIDPAUSE_REBUILD_MAX_AGE_MS	Max age of mid-pause metadata used for full-history rebuild (default: 15 min).

Architecture notes

Stream modules are split under src/stream/:

Module	Responsibility
types.ts	Shared structural types (no runtime code — safe for anyone to import)
config.ts	Agent URL + client version resolution
tuning.ts	Timeouts, retry budgets, and the stream idle watchdog
debug-log.ts	Debug / lifecycle / metric sinks with secret redaction
images.ts	Image decode + Cursor CLI format and size validation
model-routing.ts	Effort suffix / requested model resolution
model-discovery.ts	GetUsableModels unary RPCs + per-token model cache
context-normalize.ts	Context-mode side-channel folding
message-parsing.ts	Pi/OpenAI message list → Cursor turn structures
pi-adapter.ts	Pi context/model types ↔ OpenAI-shaped request, usage accounting
request-build.ts	AgentRunRequest protobuf construction + blob store
bridge-session.ts	Active-bridge registry + h2-bridge lifecycle
session-state.ts	Conversation store, checkpoints, key derivation, session locks
server-messages.ts	Inbound KV / exec / interaction dispatch
thinking-filter.ts	Strips inline <think>-style tags from the text channel
recovery.ts	Tool-continuation recovery planner
protocol.ts	Auth/protocol error enhancement
drift.ts	Wire-drift detection (unknown message cases and protobuf fields)
native-core.ts	Native streamSimple runtime that drives all of the above

Native streamSimple is the only chat path. The OpenAI-compatible local proxy that used to sit alongside it was removed in favour of a single code path.

src/proto/agent_pb.ts is a large generated Connect/protobuf surface used by the wire layer. Never hand-edit it — regenerate with npm run proto:gen (see proto/README.md) when Cursor changes the agent schema.

Troubleshooting

• No API provider registered for api: cursor-native: Update to the latest pi-cursor (pi update npm:@rahularya01/pi-cursor) and restart Pi (or /reload). This means the Agent tried to stream via Pi's global streamSimple dispatcher before the Cursor transport was registered there. Current builds register cursor-native on that registry during extension load.
• Not logged in / 401: Ensure Cursor CLI or app is logged in, or run /login cursor again. Check /cursor.doctor to verify your tokenSource. Tokens from CLI/IDE are re-resolved when near expiry; idle stream retries also force-refresh credentials.
• Empty / hung stream: Cursor may have updated wire headers; verify network connectivity or bump PI_CURSOR_CLIENT_VERSION. /cursor.doctor prints the active clientVersion.
• Wire-protocol drift: Cursor can change agent.v1 at any time. Unrecognized server messages and unknown protobuf fields are no longer skipped silently — they are counted, written to the lifecycle log as wire_drift, appended to the failing turn's error message, and listed by /cursor.doctor under wireDrift. wireDriftStranding=yes means an unanswered message could have parked the turn, which is the difference between "our schema is a bit behind" and "this is why it hung". Run CURSOR_ACCESS_TOKEN=... npm run smoke:wire to check the handshake and schema against the live endpoint without starting a chat turn, then see proto/README.md to resync the schema.
• Stuck / dies after a few minutes of work: v1.2.2 answers all Cursor InteractionQuery permission prompts (web search / ask-question / etc.) that previously parked the stream. Inspect $TMPDIR/pi-cursor-lifecycle.jsonl for interaction_query / bridge_close events, and /cursor.doctor for lastStreamEvent. Full debug: PI_CURSOR_PROVIDER_DEBUG=1.
• Tool continuation lost: The provider now prefers full-history rebuild when checkpoints are stale/mismatched. If recovery still skips, /cursor.doctor shows lastRecoverySkipReason. Retry the turn or start a new chat.
• WSL credential detection: Ensure your Windows user profile folder exists under /mnt/c/Users/ and is readable from WSL. Disable with PI_CURSOR_SYSTEM_CREDENTIALS=0 if undesired.

Development

npm install
npm run check

npm run check runs TypeScript typechecking, ESLint, Prettier format verification, security checks, the protobuf staleness check, and unit tests.

Script	Purpose
npm run proto:gen	Regenerate src/proto/agent_pb.ts from proto/agent.proto.
npm run proto:sync	Rebuild proto/agent.proto from an updated generated file obtained upstream.
npm run proto:check	Fail if the generated protobuf is stale or hand-edited (part of npm run check).

Attributions

Wire protocol and authentication patterns adapted from MIT community client lineage:

• ephraimduncan/opencode-cursor
• @pi-stef/cursor

Package structure mirrors pi-antigravity.

License

MIT