> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ccs.kaitran.ca/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor IDE Bridge (Legacy)

> Deprecated compatibility bridge for the older local Cursor daemon workflow

# Cursor IDE Bridge (Legacy)

<Badge>Beta</Badge>

This page documents the **deprecated local Cursor IDE bridge**. It is still
available for migration and backward compatibility, but it is no longer the
current `ccs cursor` product surface.

<Warning>
  Use [`ccs cursor --auth`](/providers/oauth/cursor) for the **current Cursor
  provider path**. The commands on this page now live under
  `ccs legacy cursor ...`.
</Warning>

<Warning>
  **Beta Feature — Use at Your Own Risk**

  * Uses Cursor's internal ConnectRPC API (reverse-engineered, may break on IDE updates)
  * Tokens expire every 24h and must be re-imported
  * Windows users must use manual auth (`--manual` flag)
</Warning>

## Quick Start

```bash theme={null}
ccs legacy cursor enable        # Enable the legacy bridge in config
ccs legacy cursor auth          # Auto-detect credentials from Cursor SQLite
ccs legacy cursor start         # Start local daemon
ccs legacy cursor probe         # Verify runtime health
ccs legacy cursor status        # Inspect auth + daemon state
```

Older `ccs cursor <subcommand>` invocations are still shimmed for a migration
window, but they print a deprecation warning and forward to the legacy bridge.

On macOS and Linux, auto-detect requires `sqlite3` in your `PATH`. Windows does
not support auto-detect.

## Authentication

CCS auto-detects credentials from Cursor's local SQLite database.

| Platform | SQLite Path                                                           |
| -------- | --------------------------------------------------------------------- |
| macOS    | `~/Library/Application Support/Cursor/User/globalStorage/state.vscdb` |
| Linux    | `~/.config/Cursor/User/globalStorage/state.vscdb`                     |
| Windows  | Manual only — see below                                               |

```bash theme={null}
# Auto-detect (macOS/Linux)
ccs legacy cursor auth

# Manual import
ccs legacy cursor auth --manual --token <access-token> --machine-id <32-hex-id>
```

Credentials are stored at `~/.ccs/cursor/credentials.json` (mode `0o600`).

<Note>
  Auto-detect uses the `sqlite3` CLI on macOS and Linux. If `sqlite3` is
  missing, use manual import.
</Note>

<Info>
  Token validation: access token must be >50 chars, machine ID must be exactly 32 hex characters. Tokens expire after 24h (or per JWT `exp` claim).
</Info>

## CLI Subcommands

| Subcommand | Description                               |
| ---------- | ----------------------------------------- |
| `auth`     | Import token (auto-detect or `--manual`)  |
| `status`   | Show integration, auth, and daemon status |
| `models`   | List available models with 5-min cache    |
| `start`    | Start local daemon                        |
| `stop`     | Stop daemon gracefully                    |
| `enable`   | Enable integration in `config.yaml`       |
| `disable`  | Disable integration in `config.yaml`      |
| `help`     | Show help                                 |

## Configuration

```yaml theme={null}
# ~/.ccs/config.yaml
cursor:
  enabled: false # Must be true to use
  port: 20129 # Daemon port (default: 20129)
  auto_start: false # Auto-start daemon with CCS
  ghost_mode: true # Disable Cursor telemetry (recommended)
  model: gpt-5.3-codex # Default model
  opus_model: "" # Optional: override opus tier
  sonnet_model: "" # Optional: override sonnet tier
  haiku_model: "" # Optional: override haiku tier
```

## Available Models

Model list is discovered dynamically from `api2.cursor.sh/v1/models` with a 5-minute TTL cache. The list below reflects typical available models, but may change as Cursor updates their offering.

<AccordionGroup>
  <Accordion title="GPT Models">
    GPT-5.3 Codex (default), GPT-5.2, GPT-5.1, GPT-5, GPT-5 Fast, GPT-5 Mini
  </Accordion>

  <Accordion title="Claude Models">
    Claude 4.6 Opus, Claude 4.5 Sonnet, Claude 4.5 Haiku
  </Accordion>

  <Accordion title="Gemini & Grok">
    Gemini 3 Pro, Gemini 3 Flash, Gemini 2.5 Flash, Grok Code
  </Accordion>
</AccordionGroup>

**Model fallback:** If the requested model is unavailable in Cursor's catalog, CCS falls back to the catalog-resolved default model for the current available model list and logs a debug message.

## Dashboard Controls

Open `ccs config`, then navigate to the **Deprecated** Cursor IDE bridge page if
you still rely on the local daemon workflow.

* Import auth automatically or manually
* Start/stop the daemon
* Save runtime config (port, auto-start, ghost mode)
* Use searchable model pickers for large live catalogs
* Edit raw `~/.ccs/cursor.settings.json` when needed

## Daemon Management

The daemon spawns as a detached process and uses a settled-once pattern for startup — health is polled until the daemon signals ready or the timeout is reached (30s). Proper 413 (payload too large) responses are returned for oversized requests, and the daemon aborts cleanly on client disconnect.

**Daemon API surface:**

* `POST /v1/chat/completions` for OpenAI-compatible clients
* `POST /v1/messages` for Anthropic-compatible clients
* `GET /v1/models` for dynamic model discovery

| Path                             | Purpose                     |
| -------------------------------- | --------------------------- |
| `~/.ccs/cursor/credentials.json` | Auth credentials            |
| `~/.ccs/cursor/daemon.pid`       | Daemon PID file             |
| `~/.ccs/cursor.settings.json`    | Settings override           |
| `~/.ccs/config.yaml`             | Main config (`cursor:` key) |

Stop behavior: sends `SIGTERM`, waits 5s, escalates to `SIGKILL` if still running.

Health check: `GET /health` — expects `{ "service": "cursor-daemon" }` in response.

## Dashboard API

The CCS dashboard exposes REST endpoints for managing the integration:

| Endpoint                       | Method    | Purpose               |
| ------------------------------ | --------- | --------------------- |
| `/api/cursor/status`           | GET       | Daemon + auth status  |
| `/api/cursor/auth/auto-detect` | POST      | Import from SQLite    |
| `/api/cursor/auth/import`      | POST      | Manual token import   |
| `/api/cursor/models`           | GET       | List available models |
| `/api/cursor/daemon/start`     | POST      | Start daemon          |
| `/api/cursor/daemon/stop`      | POST      | Stop daemon           |
| `/api/cursor/settings`         | GET / PUT | Read/write config     |

## Troubleshooting

<AccordionGroup>
  <Accordion title="Auth fails — token not found">
    Ensure Cursor IDE has been launched and logged in at least once. The SQLite
    DB is only created after first login. On macOS/Linux, confirm `sqlite3` is
    installed and in `PATH`. Try `ccs legacy cursor auth --manual` if
    auto-detect continues to fail.
  </Accordion>

  <Accordion title="Daemon won't start">
    Check if port 20129 is in use: `lsof -i :20129`. Change `cursor.port` in
    `config.yaml` if needed, then restart with `ccs legacy cursor start`.
  </Accordion>

  <Accordion title="Token expired">
    Tokens expire every 24h. Re-run `ccs legacy cursor auth` to refresh
    credentials from your local Cursor installation.
  </Accordion>

  <Accordion title="Windows support">
    Auto-detect is not available on Windows. Use manual import:

    ```bash theme={null}
    ccs legacy cursor auth --manual --token <token> --machine-id <id>
    ```

    Find your token in Cursor's developer tools or Keychain equivalent.
  </Accordion>
</AccordionGroup>

## Current Recommendation

Use the legacy bridge only when you specifically need the reverse-engineered
local Cursor daemon path. For new setups:

* use [Cursor Provider](/providers/oauth/cursor) for `ccs cursor --auth`
* keep this page only for `ccs legacy cursor ...`