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

# Cursor Plugin

> Sync sessions from Cursor to OpenSync

# Cursor Plugin

The `cursor-opensync-plugin` syncs your [Cursor](https://cursor.com) AI coding sessions to OpenSync. It reads Cursor's agent transcripts and conversation history, then pushes them to your dashboard.

**Source identifier:** `cursor`

## Installation

Install globally with npm:

```bash theme={null}
npm install -g cursor-opensync-plugin
```

Or with yarn:

```bash theme={null}
yarn global add cursor-opensync-plugin
```

Verify the installation:

```bash theme={null}
cursor-sync --version
```

## Setup

<Steps>
  <Step title="Generate an API key">
    Log in to [opensync.dev](https://www.opensync.dev), go to **Settings**, and click **Generate API Key**. Copy the key (starts with `osk_`).
  </Step>

  <Step title="Run login">
    ```bash theme={null}
    cursor-sync login
    ```

    Enter your Convex URL and API key when prompted:

    * **Convex URL**: `https://polished-penguin-622.convex.cloud` (for hosted) or your self-hosted URL
    * **API Key**: The key you copied from Settings
  </Step>

  <Step title="Verify the connection">
    ```bash theme={null}
    cursor-sync status
    ```
  </Step>
</Steps>

## Config file

Credentials are stored in `~/.cursor-sync/config.json`:

```json theme={null}
{
  "convexUrl": "https://polished-penguin-622.convex.cloud",
  "apiKey": "osk_..."
}
```

## Commands

### cursor-sync login

Stores your Convex URL and API key.

### cursor-sync status

Shows connection info and sync stats:

```
Connected: true
Convex URL: https://polished-penguin-622.convex.cloud
Sessions synced: 67
Last sync: 30 seconds ago
```

### cursor-sync sync

Manually triggers a sync of all sessions.

```bash theme={null}
cursor-sync sync
```

### cursor-sync logout

Clears stored credentials.

```bash theme={null}
cursor-sync logout
```

## How syncing works

1. Cursor stores conversation data in its workspace and agent transcript files.
2. The plugin reads Cursor's session data, parsing prompts, responses, tool calls, and model metadata.
3. Each session is pushed to `/sync/session` with `source: "cursor"`.
4. Messages are pushed to `/sync/message` preserving the full conversation flow.
5. Deduplication uses `externalId` from Cursor's internal session identifiers.

### What gets synced

| Data                | Synced  | Notes                                                               |
| ------------------- | ------- | ------------------------------------------------------------------- |
| User prompts        | Yes     | Full text of all user messages                                      |
| Assistant responses | Yes     | Complete model responses                                            |
| Model name          | Yes     | Whatever model Cursor used (GPT-4o, Claude, etc.)                   |
| Token counts        | Yes     | Per-message and per-session                                         |
| Tool calls          | Yes     | File edits, terminal commands, searches                             |
| File context        | Limited | File references are included, but full file contents are not synced |
| Cost estimate       | Yes     | Based on the model used                                             |

<Info>
  File contents referenced in conversations are not synced to protect sensitive code. Only file paths and the conversational text are sent.
</Info>

### Supported models

Cursor supports multiple models. All are synced with their respective pricing:

| Model                    | Provider  | Input (per 1M) | Output (per 1M) |
| ------------------------ | --------- | -------------- | --------------- |
| gpt-4o                   | OpenAI    | \$2.50         | \$10.00         |
| gpt-4o-mini              | OpenAI    | \$0.15         | \$0.60          |
| claude-sonnet-4-20250514 | Anthropic | \$3.00         | \$15.00         |
| claude-3-5-haiku         | Anthropic | \$1.00         | \$5.00          |
| o3-mini                  | OpenAI    | \$1.10         | \$4.40          |

## Troubleshooting

### Sessions not syncing

1. Make sure Cursor is not actively writing to the session files during sync. Close Cursor or wait for a pause.
2. Check plugin status: `cursor-sync status`
3. Verify the Cursor data directory is accessible.
4. Run `cursor-sync sync` to force a manual push.

### Partial sessions

Very long Cursor sessions may be truncated during sync. This is a known limitation for sessions with hundreds of messages. The most recent messages are prioritized.

### Authentication errors

1. Re-run `cursor-sync login` with your current API key.
2. Check that the API key is still active in the dashboard Settings.

## Updating

```bash theme={null}
npm update -g cursor-opensync-plugin
```

## Uninstalling

```bash theme={null}
cursor-sync logout
npm uninstall -g cursor-opensync-plugin
```

Synced sessions remain in your dashboard after uninstalling.