mirror of
https://github.com/tiennm99/ccs.git
synced 2026-07-15 20:20:09 +00:00
Tam Nhu Tran
fae8716900
- resolve request model against current available catalog - choose safe default when configured default id is not present - add tests and docs for daemon request-model fallback behavior
110 lines
2.3 KiB
Markdown
110 lines
2.3 KiB
Markdown
# 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.
|
|
- 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
|
|
|
|
```bash
|
|
ccs cursor enable
|
|
```
|
|
|
|
### 2) Import credentials
|
|
|
|
Auto-detect from Cursor local SQLite state:
|
|
|
|
```bash
|
|
ccs cursor auth
|
|
```
|
|
|
|
Manual fallback:
|
|
|
|
```bash
|
|
ccs cursor auth --manual --token <token> --machine-id <machine-id>
|
|
```
|
|
|
|
### 3) Start daemon
|
|
|
|
```bash
|
|
ccs cursor start
|
|
```
|
|
|
|
### 4) Verify status
|
|
|
|
```bash
|
|
ccs cursor status
|
|
```
|
|
|
|
### 5) Stop daemon
|
|
|
|
```bash
|
|
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.
|
|
|
|
These values are managed in unified config and can be updated from CLI or dashboard.
|
|
|
|
## Dashboard Usage
|
|
|
|
Open dashboard:
|
|
|
|
```bash
|
|
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
|
|
- 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`.
|