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.
- pi-cursor-provider
| Requirement | Details |
|---|---|
| Pi Coding Agent | npm install -g @mariozechner/pi-coding-agent (v0.53.0+) |
| Cursor Agent CLI | Installed and available on PATH (or provide the path via CURSOR_AGENT_PATH) |
| Cursor account | Free or paid; available models depend on your subscription |
pi install npm:@netandreus/pi-cursor-providerOr for project-local install:
pi install npm:@netandreus/pi-cursor-provider -lFrom the repository root:
git clone https://github.com/netandreus/pi-cursor-provider.git
cd pi-cursor-provider
pi install .pi -e npm:@netandreus/pi-cursor-providerpi remove npm:@netandreus/pi-cursor-provider# You can find installed path right after running "pi"
pi remove ~/sandbox/pi-cursor-providerThe provider delegates authentication entirely to the Cursor CLI. Your Cursor credentials are stored and managed by the CLI itself (~/.cursor/).
# Option 1 — Interactive browser-based login (recommended)
agent login
# Option 2 — API key
export CURSOR_API_KEY=your_cursor_api_keyIf CURSOR_API_KEY is set it is forwarded to every agent subprocess via --api-key automatically.
After loading the extension you can manage auth without leaving Pi. These commands appear in the command palette (e.g. when you type /cur):
| Command | Description |
|---|---|
/cursor-login |
Log in to Cursor (runs agent login) |
/cursor-status |
Show Cursor authentication status (runs agent status) |
/cursor-logout |
Log out of Cursor (runs agent logout) |
/cursor-models-refresh |
Refresh the cached Cursor model catalog (runs agent models) |
agent status
# or inside Pi:
# /cursor-statusExpected 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/sonnet-4.6-thinking
/model cursor/gpt-5.2
/model cursor/gemini-3-pro
You can also specify the model on the command line:
pi -e npm:@netandreus/pi-cursor-provider --provider cursor --model autoOr pipe a prompt non-interactively:
echo "Explain the main function in this file" | \
pi -e npm:@netandreus/pi-cursor-provider --provider cursor --model sonnet-4.6At startup the extension registers models from a disk cache (~/.pi/agent/cursor-models-cache.json, or CURSOR_MODELS_CACHE) so Pi does not block on agent models (which commonly takes ~2–3s). If the cache is missing or older than 24h, discovery runs after session_start in the background, then hot-updates the registered provider models.
If no cache exists yet, a built-in static fallback list is used immediately. If background discovery fails (CLI missing, not authenticated, timeout), the current list is kept — no crash, no user action needed.
Force a refresh anytime with /cursor-models-refresh (applies immediately; no restart required).
To see the models currently available to your account:
agent modelsModels whose id contains -thinking, -high, -xhigh, or -max-high are marked as reasoning models in Pi. All other metadata (contextWindow, maxTokens) is derived from the static lookup table or set to safe defaults (200k context / 32k max tokens) for models not in the table.
When you use a canonical ID (e.g. claude-sonnet-4-5), the provider can send the thinking variant to the CLI when Pi’s reasoning level is enabled.
Subset of models supported by the provider. Use the Canonical ID with /model cursor/<id>. The full list is discoverable via agent models.
| Canonical ID | CLI model ID | Name | Reasoning |
|---|---|---|---|
auto |
auto |
Auto | — |
claude-sonnet-4-5 |
sonnet-4.5, sonnet-4.5-thinking |
Claude 4.5 Sonnet | yes (thinking variant) |
claude-sonnet-4-6 |
sonnet-4.6, sonnet-4.6-thinking |
Claude 4.6 Sonnet | yes (thinking variant) |
claude-opus-4-5 |
opus-4.5, opus-4.5-thinking |
Claude 4.5 Opus | yes (thinking variant) |
claude-opus-4-6 |
opus-4.6, opus-4.6-thinking |
Claude 4.6 Opus | yes (thinking variant) |
gpt-5.2 |
gpt-5.2, gpt-5.2-high |
GPT-5.2 | yes (high variant) |
gpt-5.2-codex |
gpt-5.2-codex, -low, -high, -xhigh |
GPT-5.2 Codex | yes (level variants) |
gpt-5.2-codex-fast |
gpt-5.2-codex-fast, -low-fast, … |
GPT-5.2 Codex Fast | yes (level variants) |
gpt-5.3-codex |
gpt-5.3-codex, -low, -high, -xhigh |
GPT-5.3 Codex | yes (level variants) |
gpt-5.3-codex-fast |
gpt-5.3-codex-fast, … |
GPT-5.3 Codex Fast | yes (level variants) |
gpt-5.1 |
gpt-5.1-high |
GPT-5.1 High | yes |
gpt-5.1-codex-max |
gpt-5.1-codex-max, -max-high |
GPT-5.1 Codex Max | yes |
gemini-3-pro-preview |
gemini-3-pro |
Gemini 3 Pro | — |
gemini-3-flash-preview |
gemini-3-flash |
Gemini 3 Flash | — |
grok-code-fast-1 |
grok |
Grok | — |
composer-1.5 |
composer-1.5 |
Composer 1.5 | — |
composer-1 |
composer-1 |
Composer 1 | — |
| Environment variable | Default | Description |
|---|---|---|
CURSOR_AGENT_PATH |
agent |
Full path to the Cursor Agent CLI binary. |
AGENT_PATH |
agent |
Fallback if CURSOR_AGENT_PATH is not set. |
CURSOR_API_KEY |
(none) | Cursor API key; passed to CLI via --api-key if set. |
CURSOR_MODELS_CACHE |
~/.pi/agent/cursor-models-cache.json |
Path to the on-disk model catalog cache used for non-blocking startup. |
Example:
export CURSOR_AGENT_PATH=$HOME/.local/bin/agent
pi -e npm:@netandreus/pi-cursor-provider --provider cursor --model autoEach Pi turn spawns a Cursor Agent CLI subprocess:
agent --print --output-format stream-json --model <id> --trust --workspace <cwd> "<prompt>"
The extension serialises the Pi conversation (system prompt + message history) into a single text prompt that is passed to the CLI. The CLI's NDJSON stdout is read line-by-line; type: "assistant" events are mapped to Pi stream events (text_start, text_delta, text_end, done).
- Multi-turn context: The full message history is serialised as a prefixed transcript (
[User] / [Assistant] / [Tool result]) and sent as a single prompt. Cursor manages its own internal conversation from that point. - Token usage: Cursor CLI does not expose token counts; usage is reported as 0.
- Cost tracking: Models are registered with
cost: 0since billing goes through your Cursor subscription.
When the Cursor CLI uses tools (Read, Write, Shell, Grep, Ls, Glob, etc.) during a turn, the extension displays those calls inline with the assistant text.
The Cursor CLI executes all tools itself — Pi only observes and displays them. Tool arguments and results originate in the Cursor agent's execution environment, not in Pi's tool system.
Supported Cursor CLI tools that appear in Pi's output:
| CLI event key | Display name |
|---|---|
shellToolCall |
Shell |
readToolCall |
Read |
editToolCall |
Edit |
writeToolCall |
Write |
deleteToolCall |
Delete |
grepToolCall |
Grep |
globToolCall |
Glob |
lsToolCall |
Ls |
todoToolCall |
Todo |
webFetchToolCall |
WebFetch |
webSearchToolCall |
WebSearch |
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 listExample output:
pi-auto: not loaded (needs approval)
Enable and approve the server:
agent mcp enable pi-autoExample output:
✓ Enabled and approved MCP server: pi-auto
Verify tools are available:
agent mcp list-tools pi-autoExample 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 does not support image attachments in --print mode. When Pi messages contain images (e.g. screenshots), the provider serialises them as a textual placeholder:
[Image: image/png, ~48320 bytes — note: image input is not supported by the Cursor Agent CLI; the visual content cannot be passed through]
- The text of the conversation is still sent and a response is returned.
- The model is informed that an image was attached but cannot see its contents.
- Models are registered with
input: ["text"]only to reflect this limitation.
Image input will be enabled automatically if a future Cursor CLI version adds an attachment flag.
- Image content cannot be passed to the model (Cursor CLI limitation — see above).
- Multi-turn history is serialised as plain text; very long conversations may exceed the model's context window.
- Token usage is always reported as 0 (the Cursor CLI does not expose token counts).
| Symptom | Likely cause | Fix |
|---|---|---|
spawn agent ENOENT |
agent binary not on PATH |
Set CURSOR_AGENT_PATH=/path/to/agent |
| Empty response / hangs | Not logged in to Cursor | Run agent login or set CURSOR_API_KEY |
No models available |
Cursor CLI cannot reach the API | Check internet connection and agent status |
| Error on a specific model | Model not in your subscription | Run agent models or /cursor-models-refresh |
| Missing newly released models | Cache still serving previous catalog | Run /cursor-models-refresh |
| NDJSON parse errors | Unexpected CLI output | Check stderr; update Cursor Agent CLI |