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.
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.6Inside Pi:
- Run
/login. - Select Use an API key → Cursor.
- Paste your key.
- Run
/cursor-refresh-models. - Enter your prompt.
Keep your key out of cursor-sdk.json and shared logs. See installation options for GitHub and project-local installs.
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:slowThe 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:
| Command | Action |
|---|---|
/cursor-fast |
Toggle and save fast mode for the selected model, when supported. Select the model without :fast or :slow to change its default. |
/cursor-mode plan |
Use Cursor plan mode. Use /cursor-mode agent to return to agent mode. |
/cursor-refresh-config |
Reload filesystem settings in the current Cursor agent. |
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.
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.
Pi's --no-tools, --tools, and --exclude-tools do not disable Cursor tools or Cursor MCP servers. Use Cursor settings to change those tools.
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.
# 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.6Cursor activity cards show recorded results. They do not run tools again. 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.
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.
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.
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.
| Problem | Action |
|---|---|
| Models appear, but a run fails | Run /login with an API key for Cursor SDK. Run /cursor-refresh-models. |
| First reply is slow | Check configured Cursor MCP servers. Read settings and connection limits. |
| Streams fail behind a VPN or proxy | Run /cursor-http on. This changes the local SDK transport only. |
| Fallback catalog remains with a saved key | Read the startup refresh limit for official Pi 1.0.4 and 1.1.0. |
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.
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.
MIT · Mitch Fultz