Cursor Composer 2.5 Pi Extension

Delegates explicit tasks from Pi to Cursor SDK using composer-2.5.

It also registers a native Pi custom model provider:

cursor-composer/composer-2.5

This provider wraps Cursor SDK local-agent runs, so it behaves more like a delegated agent than a raw chat-completions model. While Cursor is doing long internal tool runs, the provider emits periodic thinking/progress heartbeats so Pi Web UI does not look silent.

Install

From npm after publish:

pi install npm:@firstpick/pi-extension-cursor-composer

For local development from this repository:

# Option A: install as a local package
pi install ./pi-extension-cursor-composer

# Option B: live-link all repo Pi packages for development
./dev/scripts/sync-pi-package-symlinks.sh
cd pi-extension-cursor-composer
npm install

The package depends on @cursor/sdk. Published/local pi install installs that dependency automatically; the repo symlink workflow needs the package-local npm install step because the sync script only creates symlinks. Then reload Pi with /reload.

Configure auth

Set CURSOR_API_KEY, or run:

/cursor-composer-setup

The setup command can save the key to Pi global .env, workspace .env, or only the current process. It then asks whether to add cursor-composer/composer-2.5 to Pi's enabledModels scoped-model list in ~/.pi/agent/settings.json.

If you already have a scoped model list, setup appends Composer 2.5. If you do not, adding it creates an explicit scoped list; use /scoped-models afterward if you want to include other models too.

Commands

• /cursor-composer-status — check API key, SDK install status, native provider id, and scoped-model status.
• /cursor-composer-add-scoped-model — add cursor-composer/composer-2.5 to Pi enabledModels.
• /cursor-composer-models — list Cursor models visible to the key and verify composer-2.5.
• /cursor-composer [flags] <prompt> — run Composer 2.5 on a prompt.

Flags:

• --plan / --agent
• --thinking=low|medium|high
• --sandbox
• --no-auto-review
• --cwd=subdir or --workspace-subdir=subdir

Example:

/cursor-composer --plan --thinking=high Review this repo and propose the safest migration plan.

Native Pi model

After setup and /reload, check:

CURSOR_API_KEY=crsr_... pi --list-models | grep cursor-composer

In Pi, it should appear as:

cursor-composer/composer-2.5

Use /model to select it, or add it through setup//cursor-composer-add-scoped-model for scoped Ctrl+P cycling. Changes to enabledModels are persisted, but the current session's scoped list may need /scoped-models, /reload, or a new session to refresh.

Provider usage/status behavior:

• The native provider forwards Cursor SDK turn-ended usage into Pi assistant-message usage, so git-footer-status can show input/output tokens, cache read/write tokens, cost, context, and speed.
• If the installed Cursor SDK does not emit final usage, the provider estimates input/output tokens from prompt/output text and records a cursor-composer.usage_estimated diagnostic; cache tokens are not estimated.
• Pricing defaults to Cursor's fast Composer 2.5 tier because Cursor documents Fast as the product default: $3/M input and $15/M output. Standard pricing is $0.50/M input and $2.50/M output.
• Set CURSOR_COMPOSER_PRICE_TIER=standard to use standard pricing, or override individual rates with CURSOR_COMPOSER_INPUT_COST_PER_MILLION, CURSOR_COMPOSER_OUTPUT_COST_PER_MILLION, CURSOR_COMPOSER_CACHE_READ_COST_PER_MILLION, and CURSOR_COMPOSER_CACHE_WRITE_COST_PER_MILLION.
• Cursor publishes input/output prices, not a separate cache discount; cache read/write rates default to the active input rate unless overridden.
• Default verbosity is quiet: show one short working line, final assistant text, requests, and errors.
• Set CURSOR_COMPOSER_PROVIDER_VERBOSITY=normal to include tool/status progress.
• Set CURSOR_COMPOSER_PROVIDER_VERBOSITY=debug to include rawer Cursor stream details.
• CURSOR_COMPOSER_PROVIDER_HEARTBEAT_MS=15000 controls quiet heartbeat checks; only normal/debug show repeated heartbeat lines.
• Set CURSOR_COMPOSER_PROVIDER_HEARTBEAT_MS=0 or false to disable heartbeats entirely.
• Set CURSOR_COMPOSER_PROVIDER_AUTO_REVIEW=false to disable Cursor local auto-review.
• Set CURSOR_COMPOSER_PROVIDER_SANDBOX=true to enable Cursor SDK sandboxing for native model runs.
• Large Pi toolResult messages are truncated by default before they are replayed into the native provider prompt. This keeps previous read/bash dumps from being resent to Cursor on every turn while preserving the message header, head/tail previews, original size, content hash, and a deterministic Recovery ID. Truncation uses Pi's normal tool-output byte and line limits.
• When a provider prompt contains truncated tool results, the local Cursor agent also receives an ephemeral pi_get_truncated_tool_result custom tool. Composer can call it with the Recovery ID and an optional line range to fetch exact omitted historical content for that provider run without replaying every large output up front. Recovery IDs are deterministic for the same persisted tool result, but the recovery map itself is rebuilt per provider run rather than stored separately.
• Set CURSOR_COMPOSER_PROVIDER_TRUNCATE_TOOL_RESULTS=false to restore the previous full tool-result replay behavior.

Tool

The extension registers cursor_composer_agent for Pi to call when you explicitly ask to use Cursor/Composer.

By default, tool use requires interactive confirmation because Cursor SDK local mode can run commands and edit files. To allow unattended runs, set:

export CURSOR_COMPOSER_REQUIRE_CONFIRMATION=false

Use that only if you accept unattended Cursor SDK tool execution.