fitchmultz/pi-cursor-sdk

pi‑cursor‑sdk – Connect Cursor’s LLMs to Pi’s terminal UI

What it is

• An open‑source extension that runs the Cursor SDK agent locally and wires it into the Pi terminal‑based AI assistant. It lets Pi users select and invoke Cursor models (e.g., grok‑4.6, gpt‑5.5) and use Cursor’s built‑in tools (file editing, shell commands, MCP servers) from within Pi sessions.

Why it matters

• Combines two emerging AI developer tools: Cursor (a code‑centric LLM platform with tool‑use capabilities) and Pi (a terminal UI for conversational AI). Users get the rich tool ecosystem of Cursor while staying inside Pi’s familiar command‑line workflow.

Key capabilities

• Model selection – Choose any Cursor model with pi --model cursor/<model>; supports context‑window tags (@1m) and speed modes (:fast, :slow).
• Thinking level – Adjust Cursor’s “thinking” parameter via --thinking flag.
• Tool bridge – Exposes Pi extension tools to Cursor as pi__* functions, enabling Cursor‑side tool calls.
• Fast/plan modes – Toggle Cursor’s fast mode and plan mode with /cursor-fast and /cursor-mode commands.
• Local & cloud runtimes – Run the Cursor agent locally (default) or in Cursor Cloud (/cursor-runtime cloud).
• Billing visibility – Separate Cursor usage stats (/cursor-usage) from Pi’s native accounting.
• Safety & config – Environment variables to disable the Pi‑Cursor tool bridge, ignore local Cursor settings, and control HTTP transport.

Getting started

1. Prerequisites – Node 24+, Pi 0.87.1+, and a Cursor SDK API key (user‑level key, not a team‑admin key).
2. Install via Pi’s package manager:

   pi install npm:pi-cursor-sdk
   pi --model cursor/grok-4.6   # or any other model
   

3. Inside Pi:
   • Run /login → Use an API key → Cursor → paste your key.
   • Refresh the model catalog with /cursor-refresh-models.
   • Issue prompts as usual.

Configuration shortcuts

• Startup flags: --cursor-fast, --cursor-no-fast, --cursor-mode plan.
• Environment variables:
  • PI_CURSOR_FOOTER=0 – hide status footer.
  • PI_CURSOR_PI_TOOL_BRIDGE=0 – turn off the Pi‑Cursor tool bridge.
  • PI_CURSOR_SETTING_SOURCES=none – ignore local Cursor config files.

Troubleshooting highlights

Symptom	Quick fix
Model list shows but calls fail	Re‑login with a valid Cursor SDK key and run /cursor-refresh-models.
First reply is slow	Verify MCP server settings; see the “first‑cursor‑message‑is‑slow” docs.
Streams drop behind VPN/proxy	Enable HTTP transport with /cursor-http on.

Documentation

• Full reference: docs/reference.md
• Development notes: docs/development.md
• Model UX spec for maintainers: docs/cursor-model-ux-spec.md
• Changelog and licensing are provided.

License

• MIT © Mitch Fultz.

---

pi‑cursor‑sdk is a genuine, functional bridge between two AI‑focused developer tools, enabling seamless use of Cursor’s LLMs and tool ecosystem inside Pi’s terminal UI.