English | 简体中文

A Pi Coding Agent custom provider that routes model requests through the Cursor Agent CLI, enabling you to use any model available on your Cursor subscription — Claude (Opus, Sonnet), GPT, Gemini, Grok, and more — from inside Pi.

No separate API keys are needed for the models themselves. Authentication is handled by the Cursor CLI using your existing Cursor account.

Published as @jiah-liu/pi-cursor-provider, a fork of @netandreus/pi-cursor-provider.

• pi-cursor-provider
  • Contents
  • Prerequisites
  • Installation
    • Option A — Install from npm (recommended)
    • Option B — Install from source
    • Option C — Try without installing
  • Uninstall
    • Option A — Installed from npm (recommended)
    • Option B — Installed from source
  • Authentication
    • First-time setup
    • Auth commands inside Pi
    • Verify auth
  • Usage
  • Available models
    • Model synchronization
    • Model reference table
  • Configuration
  • How it works
  • Tool calls
  • Installing and enabling MCP tools in Cursor Agent for Pi
  • Image input
  • Limitations
  • Troubleshooting
  • References
  • License

pi install npm:@jiah-liu/pi-cursor-provider

Or for project-local install:

pi install npm:@jiah-liu/pi-cursor-provider -l

From the repository root:

git clone https://github.com/jiah-liu/pi-cursor-provider.git
cd pi-cursor-provider
pi install .

pi -e npm:@jiah-liu/pi-cursor-provider

pi remove npm:@jiah-liu/pi-cursor-provider

# You can find installed path right after running "pi"
pi remove ~/sandbox/pi-cursor-provider

The provider delegates authentication entirely to the Cursor CLI. Your Cursor credentials are stored and managed by the CLI itself (~/.cursor/).

Pi 0.77+ no longer requires CURSOR_API_KEY to be set for this provider: agent login is enough. Set CURSOR_API_KEY only if you want to pass a dashboard key into the CLI.

# Option 1 — Interactive browser-based login (recommended)
agent login

# Option 2 — API key
export CURSOR_API_KEY=your_cursor_api_key

If CURSOR_API_KEY is set it is inherited by every agent subprocess without exposing it in command-line arguments.

After loading the extension you can manage auth without leaving Pi. These commands appear in the command palette (e.g. when you type /cur):

When a Cursor model is selected without CURSOR_AGENT_TRUST=1, interactive Pi prompts for workspace permissions before the first request. The choice updates the current Pi process only; use the environment variables below for a persistent default.

agent status
# or inside Pi:
# /cursor-status

Expected output when authenticated:

 ✓ Logged in as you@example.com

After loading the extension, select a Cursor model with the /model command:

/model cursor/auto
/model cursor/composer-2.5
/model cursor/claude-opus-4-8
/model cursor/gpt-5.5
/model cursor/gemini-3.1-pro

You can also specify the model on the command line:

pi -e npm:@jiah-liu/pi-cursor-provider --provider cursor --model auto

Or pipe a prompt non-interactively:

echo "Explain the main function in this file" | \
  pi -e npm:@jiah-liu/pi-cursor-provider --provider cursor --model claude-opus-4-8

At startup the extension runs agent models to discover the account-specific model list from your Cursor subscription. The list is cached for the lifetime of the Pi session.

New Cursor models are picked up automatically when Pi starts. In an existing interactive session, run /reload to refresh them. This requires the installed Cursor Agent CLI and your account to expose the model through agent models; updating this npm package is normally unnecessary.

Cursor CLI now exposes many parameterized variants (effort, thinking, fast). The provider groups them into families so /model stays usable — for example claude-opus-4-8-thinking-high-fast is registered as cursor/claude-opus-4-8. Pi's reasoning level is mapped back to the matching CLI variant.

If discovery fails (e.g. the CLI is not installed, not authenticated, or times out), only the built-in auto fallback is registered — no crash, no stale model list.

To see the models currently available to your account:

agent models

Models with thinking or multiple effort variants are marked as reasoning models in Pi. The CLI does not expose token limits, so unknown models use conservative 200k / 32k defaults.

Old ids such as claude-sonnet-4-6 or sonnet-4.6 still resolve to the current family.

Subset of families. Use the Family ID with /model cursor/<id>. The live list comes from agent models.

Example:

export CURSOR_AGENT_PATH=$HOME/.local/bin/agent
pi -e npm:@jiah-liu/pi-cursor-provider --provider cursor --model auto

Each Pi turn spawns a Cursor Agent CLI subprocess:

agent --print --output-format stream-json --stream-partial-output \
  --model <id> --workspace <cwd>
# CURSOR_AGENT_FORCE=1 adds --force; CURSOR_AGENT_TRUST=1 adds --trust --approve-mcps
# CURSOR_AGENT_TIMEOUT_MS sets a per-request timeout (default: 600000)

The prompt is written to stdin (not argv) so long sessions do not hit Linux MAX_ARG_STRLEN / E2BIG. The CLI's NDJSON stdout is read line-by-line; streaming assistant deltas are mapped to Pi text_* events, and tool_call events become thinking_* traces. Duplicate buffered flushes (model_call_id / final flush without timestamp_ms) are skipped; growing text snapshots are converted to suffixes.

• Multi-turn context: The first request serialises the full Pi history as a prefixed transcript ([User] / [Assistant] / [Tool result]). Later requests resume the returned Cursor chat with --resume <session_id> and send only the latest user message. The chat ID is stored with its workspace in the Pi session and is discarded after compaction, tree navigation, forking, or a workspace mismatch. If resume fails before producing text, the provider rebuilds the chat once from the full Pi context.
• Safety defaults: writes and MCP auto-approval are disabled. Set CURSOR_AGENT_FORCE=1 to allow writes, and CURSOR_AGENT_TRUST=1 to trust the workspace and approve MCP tools.
• Token usage: Cursor CLI does not expose token counts; usage is reported as 0.
• Cost tracking: Models are registered with cost: 0 since billing goes through your Cursor subscription.

When the Cursor CLI uses tools (Read, Write, Shell, Grep, Ls, Glob, etc.) during a turn, the extension shows them as Pi thinking traces between assistant paragraphs — not as ⏳ lines mixed into the answer text.

The Cursor CLI executes all tools itself. They are not emitted as Pi toolCall blocks, because Pi would otherwise try to run them again. Hide thinking in Pi if you only want the final prose.

Supported Cursor CLI tools that appear in Pi's output:

To use Pi-related MCP tools (e.g. pi-auto) when the Cursor Agent runs on behalf of Pi, connect the MCP server, enable it for the agent, and allow its tools in the CLI config.

Add the server to ~/.cursor/mcp.json. Example for pi-auto:

cat ~/.cursor/mcp.json

{
  "mcpServers": {
    "pi-auto": {
      "command": "pi-auto-mcp",
      "lifecycle": "keep-alive",
      "directTools": true
    }
  }
}

List MCP servers; new ones need approval:

agent mcp list

Example output:

pi-auto: not loaded (needs approval)

Enable and approve the server:

agent mcp enable pi-auto

Example output:

✓ Enabled and approved MCP server: pi-auto

Verify tools are available:

agent mcp list-tools pi-auto

Example output:

Tools for pi-auto (8):
- pi_get_priority ()
- pi_get_provider (scope, projectPath)
- pi_get_strategy ()
- pi_get_usage (period)
- pi_set_priority (priority)
- pi_set_provider (provider, model, scope, projectPath)
- pi_set_strategy (strategy)
- pi_suggest_provider (period)

Ensure ~/.cursor/cli-config.json allows the MCP tools. For example:

"permissions": {
  "allow": [
    "Shell(ls)",
    "Mcp(pi-auto:*)"
  ],
  "deny": []
}

Mcp(pi-auto:*) lets the agent use any tool from the pi-auto server.

The Cursor Agent CLI reads images from file paths in the prompt. When Pi messages contain images:

• If the block already has a filesystem path, that path is passed through.
• Otherwise the provider writes the image bytes to a temp file and includes the path in the prompt.

Models are registered with input: ["text", "image"]. Temp files are deleted when the turn finishes.

• The initial history is serialised as plain text, so existing structured tool calls and thinking blocks are not preserved when starting or rebuilding a Cursor chat.
• Token usage is always reported as 0 (the Cursor CLI does not expose token counts).

• Cursor Agent CLI — Overview
• Pi

MIT