Cursor Provider
Relevant source files
The following files were used as context for generating this wiki page:
The Cursor Provider in shunt enables the gateway to route LLM requests to the Cursor backend. It bridges the Anthropic Messages API used by Claude Code to Cursor's native ConnectRPC/protobuf-based AgentService. This allows users to leverage their Cursor subscriptions for inference while maintaining the Claude Code harness, including tools, skills, and image support.
The provider handles complex protocol translation, including converting Anthropic-style message structures into Cursor's StreamChatRequest and re-streaming the response as Anthropic Server-Sent Events (SSE). It supports multiple interaction modes such as Agent, Plan, and Ask via specific model ID prefixes.
Sources: README.md:213-216, blueprints/upstream/cursor.md:1-5, ARCHITECTURE.md:46-48
Architecture and Data Flow
The Cursor provider acts as a protocol translator between the gateway's inbound Anthropic Messages requests and the Cursor upstream. When a request is routed to a Cursor upstream, the CursorAdapter orchestrates the conversion of the request body, manages authentication via Cursor OAuth, and handles the streaming response.
Request Pipeline
The following diagram illustrates the lifecycle of a request through the Cursor provider:
The flow demonstrates the transformation from JSON-based Anthropic messages to binary Protobuf messages for Cursor's AgentService, followed by the re-streaming of results back to the client.
Sources: ARCHITECTURE.md:46-51, src/adapters/cursor/mod.rs
Protocol Mapping
The adapter translates Anthropic message roles and content into Cursor's internal ConversationMessage format. It supports text and image content, as well as tool results.
| Anthropic Concept | Cursor Mapping | Notes |
|---|---|---|
user role | USER | Map to ConversationMessageRole::User |
assistant role | ASSISTANT | Map to ConversationMessageRole::Ai |
image block | MessagePart::Image | Supported in ConversationMessage |
tool_use | ToolCall | Bridges to Cursor native MCP tool calls |
tool_result | ToolResult | Returned to conversation context |
Sources: src/adapters/cursor/proto.rs, README.md:215-218
Authentication
Cursor authentication utilizes the cursor_oauth mode. The gateway manages tokens stored locally, typically in ~/.shunt/cursor-auth.json.
Credential Management
- Login Flow: Users authenticate via
shunt login cursor, which initiates an OAuth flow. - Token Injection: The
CursorAdapterretrieves the stored token and injects it as aBearertoken into theAuthorizationheader for upstream requests. - Storage: Credentials are kept outside the main configuration file for security.
Sources: blueprints/upstream/cursor.md:20-25, src/auth/cursor/mod.rs, README.md:104-106
Model Routing and Interaction Modes
Cursor exposes different behaviors through "wire prefixes". Users can target specific Cursor capabilities by prefixing the model ID in the shunt configuration.
Interaction Prefixes
The provider supports the following modes by parsing prefixes from the model string:
| Prefix | Cursor Mode | Description |
|---|---|---|
cursor: | Agent | Standard agentic interaction |
cursor-agent: | Agent | Explicit Agent mode |
cursor-plan: | Plan | Cursor's planning capability |
cursor-ask: | Ask | Direct question/answer mode |
Model ID Mapping
Cursor's default model ID is default (representing "Auto"). In shunt configuration, this is often aliased to avoid confusion with Claude's auto logic.
[[models]]
id = "claude-cursor-default"
display_name = "Cursor Auto"
[models.upstream_model]
cursor = "cursor:default"
Sources: blueprints/upstream/cursor.md:27-35, README.md:213-214
Implementation Details
Protobuf Integration
The core of the provider is defined in src/adapters/cursor/proto.rs, which contains the generated or hand-implemented structures for the Cursor AgentService. Key structures include:
StreamChatRequest: The main envelope for sending messages.ConversationMessage: Individual message blocks containing roles and parts (text/images).StreamChatResponse: The envelope for incoming chunks from the upstream.
Sources: src/adapters/cursor/proto.rs
Streaming Logic
The src/adapters/cursor/stream.rs module handles the translation of the upstream Protobuf stream into the Anthropic SSE format.
The sequence shows how the translator parses Protobuf messages and emits the corresponding Anthropic SSE events to the client.
Sources: src/adapters/cursor/stream.rs, README.md:215-217
Conclusion
The Cursor Provider is a critical component for users wishing to utilize Cursor's infrastructure within the Claude Code ecosystem. By implementing the native ConnectRPC protocol and providing seamless translation for messages, images, and tools, it ensures that high-level agentic features remain functional even when inference is diverted away from Anthropic.