pi-cursor-provider

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.

Prerequisites

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

Installation

Option A — Install from npm (recommended)

pi install npm:@netandreus/pi-cursor-provider

Or for project-local install:

pi install npm:@netandreus/pi-cursor-provider -l

Option B — Install from source

From the repository root:

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

Option C — Try without installing

pi -e npm:@netandreus/pi-cursor-provider

Uninstall

Option A — Installed from npm (recommended)

pi remove npm:@netandreus/pi-cursor-provider

Option B — Installed from source

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

Authentication

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

First-time setup

# 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 forwarded to every agent subprocess via --api-key automatically.

Auth commands inside Pi

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`)

Verify auth

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

Expected output when authenticated:

 ✓ Logged in as you@example.com

Usage

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 auto

Or 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.6

Available models

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.

If discovery fails (e.g. the CLI is not installed, not authenticated, or times out), a built-in static fallback list is used automatically — no crash, no user action needed.

To see the models currently available to your account:

agent models

Models 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.

Model reference table

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	—

Configuration

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.

Example:

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

How it works

Each 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: 0 since billing goes through your Cursor subscription.

Tool calls

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

Installing and enabling MCP tools in Cursor Agent for Pi

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.

1. Connect MCP server to agent

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
    }
  }
}

2. Enable the MCP server

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)

3. Allow tools from this MCP

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.

Image input

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.

Limitations

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).

Troubleshooting

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` to see available models
NDJSON parse errors	Unexpected CLI output	Check stderr; update Cursor Agent CLI

References

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
index.ts		index.ts
logo.png		logo.png
package-lock.json		package-lock.json
package.json		package.json
screenshot.png		screenshot.png
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

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 reference table

Configuration

How it works

Tool calls

Installing and enabling MCP tools in Cursor Agent for Pi

1. Connect MCP server to agent

2. Enable the MCP server

3. Allow tools from this MCP

Image input

Limitations

Troubleshooting

References

License

About

Uh oh!

Releases 1

Packages

Languages

License

netandreus/pi-cursor-provider

Folders and files

Latest commit

History

Repository files navigation

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 reference table

Configuration

How it works

Tool calls

Installing and enabling MCP tools in Cursor Agent for Pi

1. Connect MCP server to agent

2. Enable the MCP server

3. Allow tools from this MCP

Image input

Limitations

Troubleshooting

References

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Languages

Packages