Cursor IDE Compatibility

Relevant source files

The following files were used as context for generating this wiki page:

• src/cursor/cursor-daemon.ts
• src/cursor/cursor-profile-executor.ts
• src/commands/cursor-command.ts
• tests/unit/cursor/cursor-daemon.test.ts
• tests/unit/cursor/cursor-profile-executor.test.ts
• tests/unit/web-server/cursor-settings-routes.test.ts
• ui/tests/unit/ui/pages/cursor-page.test.tsx

The Cursor IDE Compatibility module is a specialized system within CCS designed to bridge the gap between Claude-based workflows and the Cursor IDE. Its primary purpose is to provide a local, authenticated runtime that mimics Anthropic and OpenAI API behaviors, allowing developers to leverage CCS-managed profiles, credentials, and models directly within the Cursor environment.

This system operates as a background daemon that handles authentication translation, environment variable injection, and lifecycle management. It ensures that Cursor can communicate with various providers (like CLIProxy) as if they were native AI backends, while maintaining the security and isolation provided by CCS.

Sources: src/cursor/cursor-daemon.ts, src/commands/cursor-command.ts, README.md

System Architecture

The Cursor compatibility layer is composed of three main components: the CLI command handler, the background daemon, and the profile executor.

Core Components

• CLI Handler: Manages user interactions via ccs legacy cursor commands, including authentication setup and daemon control.
• Cursor Daemon: A persistent background process that hosts the compatibility API, serving as a proxy between Cursor and the chosen AI provider.
• Profile Executor: Orchestrates the environment setup and process execution required to launch or connect Cursor to CCS resources.

Process Flow

The following diagram illustrates the interaction between the CCS CLI, the Cursor Daemon, and the external AI Provider.

Cursor Daemon Management

The daemon is the central piece of the compatibility layer. It manages a local server (typically on port 20129) that provides OpenAI and Anthropic compatible endpoints.

Lifecycle Control

The system tracks the daemon's state using a PID file located in the CCS directory. This allows the CLI to start, stop, and verify the ownership of the daemon process.

Feature	Description	File Reference
PID Persistence	Stores the process ID in daemon.pid to manage background execution.	src/cursor/cursor-daemon.ts
Health Checks	Validates daemon readiness via a /health endpoint returning service: "cursor-daemon".	tests/unit/cursor/cursor-daemon.test.ts
Token Security	Uses a generated CCS_CURSOR_DAEMON_TOKEN to secure internal communications.	src/cursor/cursor-daemon.ts
Port Validation	Ensures the daemon runs on a valid, non-reserved integer port.	tests/unit/cursor/cursor-daemon.test.ts

Daemon Environment Construction

When the daemon starts, it inherits and transforms specific environment variables to ensure it can act as an Anthropic-compatible caller.

// Example environment construction logic
const env = {
  CCS_CURSOR_DAEMON_TOKEN: 'generated-token',
  ANTHROPIC_AUTH_TOKEN: 'generated-token', // Used for caller auth
  // ... other variables
};

Sources: src/cursor/cursor-daemon.ts:45-70, tests/unit/cursor/cursor-daemon.test.ts:135-150

Authentication and Profile Execution

Cursor compatibility supports both automatic detection of existing Cursor credentials and manual import via CLI flags.

Authentication Methods

• Manual: Users can provide an access token and machine ID via --token and --machine-id flags.
• Import: Imports existing credentials from a Cursor installation or settings file.

Environment Variable Injection

The cursor-profile-executor generates the necessary environment for the Claude runtime, mapping specific model tiers (Opus, Sonnet, Haiku) to Cursor-compatible model IDs.

Variable	Mapping Source
ANTHROPIC_BASE_URL	Local Daemon URL (e.g., http://127.0.0.1:20129)
ANTHROPIC_MODEL	config.cursor.model
ANTHROPIC_DEFAULT_OPUS_MODEL	config.cursor.opus_model
CLAUDE_CONFIG_DIR	Isolated profile directory

Sources: src/cursor/cursor-profile-executor.ts:10-50, tests/unit/cursor/cursor-profile-executor.test.ts:40-60

Compatibility API and Endpoints

The daemon exposes specific endpoints that allow Cursor to function as if it were talking directly to a cloud provider.

Key Configuration Options

Configuration is managed through the cursor section of the CCS unified config.

Option	Type	Default	Description
enabled	boolean	false	Enables/disables Cursor compatibility.
port	number	20129	Port for the compatibility daemon.
auto_start	boolean	false	Automatically starts the daemon if not running.
ghost_mode	boolean	false	Hides the daemon process from standard process lists.

Sources: tests/unit/web-server/cursor-settings-routes.test.ts:60-100, tests/unit/cursor/cursor-daemon.test.ts:330-360

Summary

Cursor IDE Compatibility provides a robust bridge between CCS-managed AI profiles and the Cursor development environment. By running a local daemon that handles authentication translation and protocol adaptation, it allows developers to use various AI models (including local models and third-party providers) seamlessly within Cursor. The system includes comprehensive health checks, PID-based process management, and flexible authentication options to ensure a stable and secure integration.