[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-77645":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":9,"rankLanguage":9,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":9,"pushedAt":9,"updatedAt":35,"readmeContent":36,"aiSummary":37,"trendingCount":15,"starSnapshotCount":15,"syncStatus":38,"lastSyncTime":39,"discoverSource":40},77645,"pi-cursor-sdk","fitchmultz\u002Fpi-cursor-sdk","fitchmultz","Run Cursor's agent loop inside the pi coding agent via local Cursor SDK agents, with native model selection, thinking controls, fast\u002Fplan modes, image input, and MCP-bridged pi tools.",null,"TypeScript",164,7,24,5,0,3,10,135,9,2.71,"MIT License",false,"main",true,[26,27,28,29,30,31,32,33,34],"ai","cursor","cursor-sdk","npm-package","pi","pi-extension","pi-package","provider","typescript","2026-06-12 02:03:43","# pi-cursor-sdk\n\nA pi provider extension that lets pi use Cursor models through the local `@cursor\u002Fsdk` agent runtime.\n\nUse this extension if you want Cursor's model catalog inside pi while keeping pi's native model picker, thinking controls where the SDK exposes them, session restore, context display, and default footer UX.\n\n## Quick start\n\n1. Install the package:\n\n```bash\npi install npm:pi-cursor-sdk\n```\n\nOr install from GitHub:\n\n```bash\npi install https:\u002F\u002Fgithub.com\u002Ffitchmultz\u002Fpi-cursor-sdk\n```\n\n2. Start pi with a Cursor model:\n\n```bash\npi --model cursor\u002Fcomposer-2.5\n```\n\n3. In pi, run `\u002Flogin`, choose `Use an API key`, choose `Cursor`, and paste your Cursor API key.\n\nIf pi started without a key, run `\u002Fcursor-refresh-models` after `\u002Flogin` to refresh the full live Cursor model catalog without restarting pi. Inside pi, use `\u002Fmodel` to choose another Cursor model.\n\n## Requirements\n\n- Node.js 22.19+\n- pi\n- a Cursor API key saved through `\u002Flogin`, available as `CURSOR_API_KEY`, or passed with pi's `--api-key`\n\nNo global `@cursor\u002Fsdk` install is required. This package depends on `@cursor\u002Fsdk`, so normal package installation brings in the SDK version this extension was built and tested against.\n\n## Install\n\n### Global install\n\n```bash\npi install npm:pi-cursor-sdk\n```\n\nAlternative GitHub install:\n\n```bash\npi install https:\u002F\u002Fgithub.com\u002Ffitchmultz\u002Fpi-cursor-sdk\n```\n\n### Project-local install\n\nUse `-l` if you want the package recorded in the current project's `.pi\u002Fsettings.json` instead of your global pi settings:\n\n```bash\npi install -l npm:pi-cursor-sdk\n```\n\n### Try from a local checkout\n\nFor development from this repository:\n\n```bash\nnpm install\npi -e . --model cursor\u002Fcomposer-2.5\n```\n\n## Configure your Cursor API key\n\nPreferred setup:\n\n```bash\npi --model cursor\u002Fcomposer-2.5\n```\n\nThen, inside pi:\n\n1. Run `\u002Flogin`.\n2. Select `Use an API key`.\n3. Select `Cursor`.\n4. Paste your Cursor API key.\n5. The key is saved in pi's native `~\u002F.pi\u002Fagent\u002Fauth.json`.\n\nIf pi started without a key, fallback Cursor models still register so `\u002Flogin` is reachable. After `\u002Flogin`, fallback model runs can use the stored key, and `\u002Fcursor-refresh-models` refreshes the full live Cursor model catalog discovered from the Cursor SDK without restarting pi.\n\nEnvironment setup:\n\n```bash\nexport CURSOR_API_KEY=\"your-key\"\npi --model cursor\u002Fcomposer-2.5\n```\n\nOne-shot setup:\n\n```bash\npi --api-key \"your-key\" --model cursor\u002Fcomposer-2.5 --cursor-no-fast -p \"Say ok only.\"\n```\n\nDiscovery uses pi's native resolution order for this extension: `--api-key`, the stored `cursor` key in `~\u002F.pi\u002Fagent\u002Fauth.json`, then `CURSOR_API_KEY`.\n\nDo not store the API key in `~\u002F.pi\u002Fagent\u002Fcursor-sdk.json`. That file is only for non-secret extension state such as Cursor fast defaults. `PATH` is only for executable lookup and should not contain the API key.\n\n## Verify your setup\n\nList Cursor models:\n\n```bash\npi --list-models cursor\n```\n\nExpected behavior:\n\n- with a valid key, Cursor models appear under the `cursor` provider\n- if discovery cannot authenticate or reach Cursor, pi may still show fallback Cursor models; after adding auth with `\u002Flogin`, fallback model runs can use the saved key, and `\u002Fcursor-refresh-models` refreshes the live catalog\n\nSmoke test:\n\n```bash\npi --model cursor\u002Fcomposer-2.5 --cursor-no-fast -p \"Reply with: ok\"\n```\n\n## Choosing a model\n\nChoose Cursor models interactively with `\u002Fmodel`, or pass a model on the command line:\n\n```bash\npi --model cursor\u002Fcomposer-2.5\npi --model cursor\u002Fgpt-5.5@1m\npi --model cursor\u002Fgpt-5.5@272k\npi --model cursor\u002Fclaude-opus-4-7@300k\n```\n\nHow to read model IDs:\n\n- `cursor\u002F...` is the Cursor provider registered by this extension\n- `@1m`, `@272k`, and `@300k` are context-window variants\n- `:medium`, `:high`, and `:xhigh` are pi thinking-level suffixes for models where the Cursor SDK exposes a pi-controllable thinking parameter\n- unambiguous latest-style Cursor aliases returned by `Cursor.models.list()` are registered too, using the same context suffixes when the target model has context variants; aliases shared by multiple base models or colliding with a base model ID are skipped because their SDK resolution and displayed metadata can diverge\n\nExamples with pi thinking controls:\n\n```bash\npi --model cursor\u002Fgpt-5.5@1m:medium\npi --model cursor\u002Fgpt-5.5@272k:xhigh\npi --model cursor\u002Fgpt-5.5@1m --thinking medium\n```\n\nCursor-only parameters are not encoded into pi model IDs. Cursor `context` becomes a pi-visible model variant because it changes pi's native `contextWindow`; Cursor `fast` is extension state, not model identity. Alias model IDs still share Cursor-only state, such as fast defaults, with their underlying Cursor base model.\n\n## Thinking support\n\nAll Cursor SDK models should be treated as thinking-capable Cursor models. The `thinking` column in `pi --list-models` is narrower: it only means pi can control a Cursor SDK thinking parameter for that model.\n\nFor models where Cursor exposes `reasoning`, `effort`, or boolean `thinking` parameters, pi's native thinking controls map to Cursor SDK params:\n\n- `reasoning=none|low|medium|high|extra-high`\n- `effort=low|medium|high|xhigh|max`\n- `thinking=false|true` for boolean thinking models\n\nFor Claude models with both `thinking` and `effort`, pi thinking `off` sends `thinking=false` and omits `effort`.\n\n### Why some Cursor models show `thinking=no`\n\nIn `pi --list-models`, `thinking=no` means pi cannot control the model's thinking level with `--thinking`, a final `:medium` model suffix, or shift+tab. It does not mean the Cursor model cannot think.\n\nSome Cursor SDK models do not expose a `reasoning`, `effort`, or `thinking` parameter for the extension to set. Cursor thinking is still enabled\u002Fsupported by the model, and Cursor may still emit thinking deltas. The extension does not disable Cursor's default reasoning behavior.\n\n## Fast mode\n\nUse `\u002Fcursor-fast` to persistently toggle fast mode for the selected Cursor model when the model supports Cursor's `fast` parameter.\n\nFast preferences are remembered per Cursor base model and stored:\n\n- in the current session with `pi.appendEntry()`\n- globally in `~\u002F.pi\u002Fagent\u002Fcursor-sdk.json`\n\nFor one run, force fast on or off without changing saved defaults:\n\n```bash\npi --model cursor\u002Fgpt-5.5@1m --cursor-fast -p \"Say ok only\"\npi --model cursor\u002Fcomposer-2.5 --cursor-no-fast -p \"Say ok only\"\n```\n\nComposer 2 and Composer 2.5 can default to fast. Use `--cursor-no-fast` for a one-shot no-fast Composer run. In print mode (`-p`), `--cursor-no-fast` is silent and does not write `~\u002F.pi\u002Fagent\u002Fcursor-sdk.json`.\n\nIn interactive mode, the footer only shows fast mode when fast is enabled:\n\n```text\ncursor fast\n```\n\nIf you do not see `cursor fast`, fast mode is off.\n\n## Images\n\nImages from the latest user message are forwarded to Cursor. Historical images are kept out of the transcript and appear only as `[image omitted from transcript]` placeholders, so follow-up questions about an earlier image should reattach the image or include a textual description. The extension advertises `text` and `image` input for Cursor models because Cursor's SDK accepts image messages and Cursor models are expected to support them.\n\n## Fallback models\n\nIf no key is available from `\u002Flogin`, `CURSOR_API_KEY`, or `--api-key`, model discovery fails, or discovery returns no models, the extension registers a bundled fallback snapshot of the latest reviewed Cursor SDK model catalog and notifies interactive users when possible.\n\nThe fallback snapshot includes Composer 2.5 (`composer-2.5` and `composer-2-5`), Composer 2, GPT, Claude, Gemini, Grok, Kimi, and other model IDs exposed by the reviewed `Cursor.models.list()` output. The exact checked-in snapshot lives in `src\u002Fcursor-fallback-models.generated.ts`.\n\nActual Cursor runs still need a key from `\u002Flogin`, `CURSOR_API_KEY`, or `--api-key`. If you add auth after startup, run `\u002Fcursor-refresh-models` to refresh the full live Cursor model catalog without restarting pi.\n\n## Limits\n\n- **Local Cursor SDK agents only.** This extension does not use Cursor cloud agents.\n- **Cursor-side tool use is not re-executed by pi.** Cursor still uses its own internal SDK tools. The extension records completed Cursor tool activity and, in interactive TTY sessions, replays supported `read`, `bash`, `grep`, `ls`, `edit`, and `write` activity through pi's native tool-call path with recorded results (for example green `read`, `grep`, `$ ...`, and Cursor edit\u002Fwrite cards) without forcing Cursor to call pi tools or rerun commands. Cursor `glob` activity is replayed through native `bash` cards with synthesized command labels. Cursor edit\u002Fwrite activity uses replay-only `cursor_edit` and `cursor_write` tool cards because Cursor's file-editing schema is not the same as pi's built-in `edit`\u002F`write` schemas; those replay tools only display recorded Cursor results and never mutate files directly. If a Cursor read completion reports no content, the extension may include a bounded local file preview for safe in-workspace paths; that preview is explicitly labeled as a local preview captured at transcript time, not guaranteed Cursor-observed content. Native replay wrappers are registered only for tool names not already owned by another extension; skipped tools fall back to the scrubbed Cursor activity transcript. As Cursor SDK tool completions arrive, the extension mirrors native Codex ordering by ending a tool-use turn, letting pi render the recorded tool results immediately, then continuing with live post-tool Cursor thinking\u002Ftext, any later Cursor tool batches, or Cursor's final answer as the next assistant turn. Non-interactive\u002Fsession consumers still get bounded scrubbed transcript data so `pi -p` keeps printing normal assistant text.\n- **Pi tool schemas are not passed through to Cursor.** This extension is a Cursor provider, not a bridge that forwards pi's tool system into Cursor.\n- **One fresh Cursor agent is created per provider call.** Cursor agent state is not reused between pi provider calls.\n- **Cursor setting sources are opt-in.** The extension does not pass `local.settingSources` by default because the Cursor SDK can print settings\u002Fskills loading output directly to the terminal during startup. To load configured Cursor MCP servers, plugin tools, project\u002Fuser settings, and related Cursor-native capabilities, start pi with `PI_CURSOR_SETTING_SOURCES=all`. To narrow loading, set a comma-separated list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`.\n- **Max Mode is not a manual pi variant.** Cursor's SDK may enable Max Mode automatically for models that require it. This extension only advertises exact context-window variants that the SDK catalog exposes and otherwise uses conservative SDK-derived default\u002Fnon-Max context windows.\n- **Output token limits are conservative.** Cursor SDK model metadata does not currently expose output token limits directly.\n- **Token usage is approximate in pi.** Cursor SDK usage events include internal agent\u002Ftool\u002Fcache work, so the extension reports an approximate replayable pi prompt\u002Foutput size for context display and compaction decisions.\n\n## Troubleshooting\n\n### I can see Cursor models, but runs fail\n\nYou may be seeing fallback startup models or a missing\u002Finvalid key. In interactive pi, run `\u002Flogin`, choose `Use an API key`, choose `Cursor`, paste the key, then run `\u002Fcursor-refresh-models`.\n\nYou can also restart pi with a key in the same shell or launcher that starts pi:\n\n```bash\nexport CURSOR_API_KEY=\"your-key\"\npi --model cursor\u002Fcomposer-2.5\n```\n\nOr run a one-shot command:\n\n```bash\npi --api-key \"your-key\" --model cursor\u002Fcomposer-2.5 -p \"Say ok only\"\n```\n\n### `pi --list-models cursor` shows no Cursor models\n\nConfirm the package is installed:\n\n```bash\npi list\n```\n\nThen reinstall if needed:\n\n```bash\npi install npm:pi-cursor-sdk\n```\n\n### `pi --list-models` shows `thinking=no`\n\nThat does not mean the model cannot think. It means the Cursor SDK does not expose a pi-controllable thinking parameter for that model. The model may still think internally and may still emit thinking deltas.\n\n### I do not see `cursor fast` in the footer\n\nFast mode is currently off. The footer only shows `cursor fast` when fast mode is enabled.\n\n### My Cursor app settings or rules do not seem to apply\n\nCursor setting sources are not loaded by default because the Cursor SDK can print settings\u002Fskills loading output directly to the terminal. Start pi with `PI_CURSOR_SETTING_SOURCES=all`, or choose a narrower list such as `PI_CURSOR_SETTING_SOURCES=project,user,plugins`.\n\n### Cursor does not call my web search MCP\u002Ftool\n\nCursor SDK local agents load MCP servers from Cursor setting sources and inline SDK config. This extension leaves Cursor setting sources off by default to avoid startup log noise, so a web search tool needs to be configured in Cursor and settings sources need to be enabled with `PI_CURSOR_SETTING_SOURCES=all` or a narrower list.\n\n### Cursor native tool cards conflict with another extension\n\nCursor native replay is a UI enhancement for interactive TTY sessions. If another extension already owns `read`, `bash`, `grep`, `ls`, `cursor_edit`, or `cursor_write`, this extension skips only the conflicting native replay wrapper and uses the scrubbed Cursor activity transcript for that tool instead. To disable Cursor native replay registration entirely, start pi with:\n\n```bash\nPI_CURSOR_NATIVE_TOOL_DISPLAY=0 pi --model cursor\u002Fcomposer-2.5\n```\n\n`PI_CURSOR_REGISTER_NATIVE_TOOLS=0` is also accepted as a registration-only opt-out.\n\n## Development\n\nRun checks:\n\n```bash\nnpm test\nnpm run typecheck\n```\n\nRefresh the reviewable Cursor fallback catalog before releases or after Cursor model changes:\n\n```bash\nCURSOR_API_KEY=\"your-key\" npm run refresh:cursor-snapshots -- --write\n```\n\nRefresh the bundled default\u002Fnon-Max context-window snapshot only when checkpoint-derived context windows have been collected from live local runs:\n\n```bash\nCURSOR_API_KEY=\"your-key\" npm run refresh:cursor-snapshots -- --write \\\n  --context-windows ~\u002F.pi\u002Fagent\u002Fcursor-sdk-context-windows.json\n```\n\nThe refresh script writes public model metadata only and scrubs known auth material from SDK errors. It must not be run with shell tracing that would echo API keys.\n\nLocal development run:\n\n```bash\nnpm install\nCURSOR_API_KEY=\"your-key\" pi -e . --model cursor\u002Fcomposer-2.5\n```\n\nMaintainer design notes live in [`docs\u002Fcursor-model-ux-spec.md`](docs\u002Fcursor-model-ux-spec.md).\n\n## License\n\nMIT\n","pi-cursor-sdk 是一个为 pi 应用程序扩展 Cursor 模型的 SDK 提供器。它允许用户在保持 pi 原生模型选择器的同时，通过本地 `@cursor\u002Fsdk` 代理运行时访问 Cursor 的模型目录。项目使用 TypeScript 编写，支持 npm 包安装和 GitHub 安装方式，确保了与最新版本的 Cursor SDK 兼容。该扩展适用于需要在 pi 环境中利用 Cursor AI 模型进行开发或研究的场景，特别是在希望保留 pi 自身用户体验（如会话恢复、上下文显示等）的情况下特别有用。用户只需简单的几步配置即可开始使用，包括安装扩展、启动带有指定模型的 pi 以及登录提供 API 密钥。",2,"2026-06-11 03:55:41","CREATED_QUERY"]