ccs/docs/cursor-integration.md

Cursor IDE Integration

This guide covers the local Cursor integration in CCS, including CLI setup, daemon lifecycle, and dashboard controls.

What It Provides

• OpenAI-compatible local endpoint powered by Cursor credentials.
• Anthropic-compatible local endpoint at /v1/messages for Claude-native clients.
• Cursor model list and chat completions via local daemon.
• Dedicated dashboard page: ccs config -> Cursor IDE.

Prerequisites

• Cursor IDE installed and logged in.
• CCS installed and configured (ccs config works).
• For auto-detect auth on macOS/Linux: sqlite3 available in PATH.

CLI Workflow

1) Enable integration

ccs cursor enable

2) Import credentials

Auto-detect from Cursor local SQLite state:

ccs cursor auth

Manual fallback:

ccs cursor auth --manual --token <token> --machine-id <machine-id>

3) Start daemon

ccs cursor start

4) Run Cursor-backed Claude

ccs cursor "explain this repo"

5) Verify status

ccs cursor status

Use ccs cursor with bare or normal Claude args to run through the local Cursor proxy. The admin namespace remains available for setup and inspection:

ccs cursor help

6) Stop daemon

ccs cursor stop

Runtime Defaults

• Default port: 20129
• ghost_mode: enabled
• auto_start: disabled
• Model list resolution: authenticated live fetch when available, with cached/default fallback.
• Request model validation: if a requested model is not present in the available Cursor model catalog, daemon falls back to the resolved default model.
• Daemon API surface: POST /v1/chat/completions, POST /v1/messages, and GET /v1/models.

These values are managed in unified config and can be updated from CLI or dashboard.

Dashboard Usage

Open dashboard:

ccs config

Then navigate to Cursor IDE in the sidebar.

Available controls:

• Integration toggle (enabled)
• Auth actions (auto-detect, manual import)
• Daemon actions (start/stop)
• Runtime config (port, auto-start, ghost mode)
• Models list with searchable combobox filtering for large catalogs
• Raw editor for ~/.ccs/cursor.settings.json

Raw Settings and Unified Config Sync

Raw settings are stored in:

~/.ccs/cursor.settings.json

When raw settings include a local ANTHROPIC_BASE_URL port override, CCS synchronizes that port back into unified config so CLI and dashboard remain consistent.

Troubleshooting

Not authenticated or expired in ccs cursor status

• Re-run ccs cursor auth (or manual auth command).

Auto-detect fails

• Ensure Cursor is logged in.
• Confirm sqlite3 is installed (macOS/Linux).
• Use manual auth import if needed.

Daemon fails to start

• Check if port 20129 is in use.
• Change port in dashboard config tab, then retry ccs cursor start.