pi-cursor-sdk

Use Cursor models in Pi's terminal UI. pi-cursor-sdk runs Cursor's SDK agent and connects it to Pi sessions and extension tools.

The agent runs locally. It sends model requests to Cursor and returns replies and tool activity to Pi.

Quick start

Requirements: Node.js 24+, Pi 0.87.1+, and an API key for Cursor SDK. The package installs @cursor/sdk for you.

Use a user key from Cursor Dashboard → API Keys or a service-account key from Team settings. Team Admin keys do not work. Cursor Desktop and Agent CLI login do not supply the SDK key.

pi install npm:pi-cursor-sdk
pi --model cursor/grok-4.6

Inside Pi:

1. Run /login.
2. Select Use an API key → Cursor.
3. Paste your key.
4. Run /cursor-refresh-models.
5. Enter your prompt.

Keep your key out of cursor-sdk.json and shared logs. See installation options for GitHub and project-local installs.

Models and controls

Use /model to select a model. Use these commands to select a model at startup:

pi --model cursor/gpt-5.5@1m --thinking medium
pi --model cursor/grok-4.6:slow

The cursor/ prefix selects this provider. @1m selects a context window from Cursor's catalog. --thinking sets the thinking level when Cursor exposes that control. Models with Cursor's fast parameter also have :fast and :slow choices.

Run pi --list-models cursor to see available models. Startup can use a cached or fallback catalog. A model in the list does not prove that your key works.

Run these commands inside Pi:

For one run, pass --cursor-fast, --cursor-no-fast, or --cursor-mode plan. See the model reference for selection rules and fast mode for saved preferences.

The footer shows status such as cursor:local · fast:off, with plan or http1 when enabled. Set PI_CURSOR_FOOTER=0 to hide the Cursor status.

Tools and settings

Cursor controls file tools, shell commands, edits, and configured MCP servers. The local MCP bridge exposes active Pi extension tools as pi__* names. The bridge is on by default. Pi hides matching built-ins from the bridge by default.

Availability: PI_CURSOR_NATIVE_TOOLS and /cursor-abort require 0.5.4 or later, beginning with the implementation from #372. Source checkouts preparing 0.5.4 remain candidates until exact publication records exist; the version change alone is not a publication record. Verify the exact npm version and GitHub release before relying on its availability. Published 0.5.3 ignores this flag and does not provide the command; do not rely on them for native-tool restriction or pending-run recovery there. Development version labels alone do not establish which controls are installed.

Pi's --no-tools, --tools, and --exclude-tools do not disable Cursor tools or Cursor MCP servers. For local ordinary turns on a supporting revision, opt in to PI_CURSOR_NATIVE_TOOLS=0 to allow only MCP through the public SDK tool surface (including disabling native task/subagents). It leaves configured Cursor MCP available unless you also disable ambient setting sources. Cloud rejects this opt-out for both ordinary and selected-Cloud summary requests; only existing isolated LOCAL summary agents remain unaffected with tools: [].

PI_CURSOR_NATIVE_TOOLS accepts 0, false, off, none, no, and disabled as off (trimmed, case-insensitive); unset, blank, or unrecognized values keep native tools on.

A policy mismatch preserves the pending local run: restore its prior policy to finish, or use /cursor-abort to explicitly release this session's pending local run before retrying. The command also stops an active owning Cursor Pi turn. Pi's normal abort only signals an active Pi turn; after the mismatch error has settled, it does not reach the old Cursor waiter. Neither recovery path undoes already-executed work.

Local runs leave Cursor auto-review and sandboxing off by default. Read the safety controls and hook limits before you depend on those controls or Cursor hooks.

# Requires 0.5.4+ containing #372; verify publication/installation (0.5.3 ignores the flag).
# MCP-only local agent; explicitly expose Pi builtins through the Pi execution path.
PI_CURSOR_NATIVE_TOOLS=0 PI_CURSOR_EXPOSE_BUILTIN_TOOLS=1 PI_CURSOR_SETTING_SOURCES=none pi --model cursor/grok-4.6

# Disable the Pi tool bridge.
PI_CURSOR_PI_TOOL_BRIDGE=0 pi --model cursor/grok-4.6

# Disable Cursor settings, rules, plugins, and MCP configuration loaded from disk.
PI_CURSOR_SETTING_SOURCES=none pi --model cursor/grok-4.6

Cursor activity cards show recorded results. They do not run tools again. Pi tool_call hooks cannot govern already-executed Cursor-native work; hiding replay or disabling the bridge is not enforcement. MCP-only is not a sandbox: exposed Pi/MCP tools can themselves execute arbitrary work. Cursor plan and todo cards do not control Pi's separate plan-mode extension or Pi todos.

See tool surfaces for bridge options and native replay for activity cards and SDK limits.

Sessions and images

The extension reuses a Cursor agent for compatible local turns. Pi can reconnect to a recorded local agent after a restart. If reconnect fails, the extension starts a new agent from the Pi transcript and shows a continuity note. See resume and storage for matching rules and cleanup commands.

Images in the current request go to Cursor. Earlier images become placeholders in the transcript. Reattach an image for a later question about it.

Usage

Pi's default footer and /stats keep their native context accounting. Use these commands for separate Cursor billing data:

/cursor-usage
/cursor-usage refresh
/cursor-usage export cursor-usage.json

Refresh requests public billing data without a model prompt. Export creates a private JSON file and does not overwrite existing files. Billing data can lag or change. It is not a final invoice.

Check paths and identifiers before you share an export. See usage and journal recovery for details.

Optional Cursor Cloud

Local is the default. Run /cursor-runtime cloud to see the first-use confirmation. Cloud can commit, push, and open PRs. It uses Max Mode billing at Cursor API pricing.

Cloud requires a persisted Pi session and starts with fresh context by default. Cloud has no local Pi tool bridge or Pi environment forwarding. Cloud agents remain in Cursor until you explicitly archive or delete them.

Run /cursor-cloud list to see agents recorded for your session branch. Read the Cloud setup and cleanup guide before you start a remote run.

Troubleshooting

See Troubleshooting for other problems. Report a bug with Pi/extension versions, model, flags, exact prompt, and a redacted session.

Debug artifacts can contain secrets. Remove secrets before you share them.

Reference and development

The full reference contains detailed configuration and limits. Development covers checks, model snapshots, and release procedures. The model UX spec contains maintainer design notes. The Changelog records version history.

License

MIT · Mitch Fultz