cursor-opensync-plugin

![npm version](https://www.npmjs.com/package/cursor-opensync-plugin)
![License: MIT](https://opensource.org/licenses/MIT)

Sync your Cursor sessions to OpenSync dashboard. Track coding sessions, analyze tool usage, and monitor token consumption across projects.

GitHub: github.com/waynesutton/cursor-cli-sync-plugin

npm: npmjs.com/package/cursor-opensync-plugin

OpenSync Ecosystem

| Project | Description | Links |
| ---------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| OpenSync | Dashboards for AI coding sessions | Website / GitHub |
| opencode-sync-plugin | Sync OpenCode sessions | GitHub / npm |
| claude-code-sync | Sync Claude Code sessions | GitHub / npm |
| droid-sync | Sync Factory Droid sessions (community built) | GitHub / npm |
| codex-sync | Sync Codex CLI sessions | GitHub / npm |
| cursor-opensync-plugin | Sync Cursor sessions | GitHub / npm |

Quick Start

$3

1. Log into your OpenSync dashboard
2. Go to Settings
3. Click Generate API Key
4. Copy the key (starts with osk_)

$3

``bash cursor-sync login`

Enter when prompted:

- Convex URL: Your deployment URL (e.g., https://your-project.convex.cloud) - API Key: Your API key from Settings (e.g.,osk_abc123...)

`$3`

Option A: Use the setup command (recommended)

`bash cursor-sync setup`

This automatically configures the hooks in ~/.cursor/hooks.json.

Option B: One-liner (copy and paste)

`bash mkdir -p ~/.cursor && cat > ~/.cursor/hooks.json << 'EOF' { "version": 1, "hooks": { "beforeSubmitPrompt": [{ "command": "cursor-sync hook beforeSubmitPrompt" }], "beforeShellExecution": [{ "command": "cursor-sync hook beforeShellExecution" }], "beforeMCPExecution": [{ "command": "cursor-sync hook beforeMCPExecution" }], "afterFileEdit": [{ "command": "cursor-sync hook afterFileEdit" }], "afterAgentResponse": [{ "command": "cursor-sync hook afterAgentResponse" }], "stop": [{ "command": "cursor-sync hook stop" }] } } EOF`

`$3`

`bash cursor-sync verify`

You should see:

`OpenSync Setup Verification

Credentials: OK Convex URL: https://your-project.convex.cloud API Key: osk_*...*

Connection: OK

Cursor Hooks: OK Config file: ~/.cursor/hooks.json Hooks registered: cursor-sync

Ready! Start Cursor and sessions will sync automatically.`

Sessions will now sync automatically when you use Cursor.

`Installation`

`bash npm install -g cursor-opensync-plugin`

`Upgrading`

To upgrade to the latest version:

`bash npm update -g cursor-opensync-plugin`

Or reinstall the latest:

`bash npm install -g cursor-opensync-plugin@latest`

After upgrading, verify everything still works:

`bash cursor-sync --version cursor-sync verify`

If you experience issues after upgrading, re-run the setup:

`bash cursor-sync setup`

`CLI Commands`

| Command | Description | | ------------------------------- | ------------------------------------------- | |cursor-sync login| Configure Convex URL and API Key | |cursor-sync setup| Add hooks to Cursor settings | |cursor-sync verify| Verify credentials and Cursor config | |cursor-sync synctest| Test connectivity and create a test session | |cursor-sync logout| Clear stored credentials | |cursor-sync status| Show connection status | |cursor-sync config| Show current configuration | |cursor-sync config --json| Show config as JSON | |cursor-sync set | Update a config value | |cursor-sync hook | Handle Cursor hook events (internal) | |cursor-sync --version| Show version number | |cursor-sync --help | Show help |

`Hook Events`

The plugin captures these Cursor events via the hooks system:

| Event | Description | | ---------------------- | ----------------------------------------------- | |beforeSubmitPrompt| Fires when you submit a prompt to the agent | |beforeShellExecution| Fires before a shell command runs | |beforeMCPExecution| Fires before an MCP tool executes | |afterFileEdit| Fires after the agent modifies a file | |afterAgentResponse| Fires after the agent completes a text response | |stop | Fires when the agent session completes |

`$3`

| Option | Type | Default | Description | | --------------- | ------- | ------- | --------------------------- | |autoSync | boolean | true| Automatically sync sessions | |syncToolCalls | boolean | true| Include tool call details | |syncThinking | boolean | false| Include thinking traces | |debug | boolean | false | Enable debug logging |

Set options with:

`bash cursor-sync set syncThinking true cursor-sync set debug true`

`Environment Variables`

You can also configure via environment variables:

`bash export CURSOR_SYNC_CONVEX_URL="https://your-project.convex.cloud" export CURSOR_SYNC_API_KEY="osk_your_api_key" export CURSOR_SYNC_AUTO_SYNC="true" export CURSOR_SYNC_TOOL_CALLS="true" export CURSOR_SYNC_THINKING="false" export CURSOR_SYNC_DEBUG="false"`

`What Gets Synced`

| Data | Description | | ------------------- | ------------------------------------------- | | Session metadata | Project path, working directory, timestamps | | User prompts | Your messages to the agent | | Assistant responses | The agent's text replies | | Tool calls | Shell commands, MCP tools, file edits | | File edit diffs | Actual code changes (old and new content) | | Message count | Number of exchanges in the session | | Tool call count | Total tool invocations |

`Feature Comparison`

Cursor's hooks API provides limited data compared to other CLI tools that expose session files. This table shows what each plugin can capture:

| Feature | cursor-sync | codex-sync | claude-code-sync | opencode-sync | | -------------------------- | :---------: | :--------: | :--------------: | :-----------: | | User prompts | Yes | Yes | Yes | Yes | | Assistant text responses | Yes | Yes | Yes | Yes | | File edit diffs | Yes | Yes | Yes | Yes | | Shell commands | Yes | Yes | Yes | Yes | | MCP tool calls | Yes | Yes | Yes | Yes | | Token usage (input/output) | No | Yes | Yes | Yes | | Cost calculation | No | Yes | Yes | Yes | | Model info per message | No | Yes | Yes | Yes |

Why the difference in token/cost data?

Other CLI tools (Codex CLI, Claude Code, OpenCode) store complete session data in local files (JSONL or SQLite). Their sync plugins read these files to extract everything including tokens and costs.

Cursor uses a hooks-based API that provides event data at lifecycle points. The hooks documentation confirms that token usage and cost information are not included in any hook payload. This is a platform limitation, not a plugin limitation.

The Cursor Analytics API and AI Code Tracking API provide aggregated team metrics but are Enterprise-only and do not expose per-session token/cost data.

`Privacy`

- All data goes to YOUR Convex deployment - Full file contents are NOT synced, only paths - Sensitive patterns are automatically redacted - Thinking traces are off by default - You control what gets synced via configuration

`How It Works`

Cursor 1.7+ introduced a hooks system that allows external scripts to run at defined stages of the agent loop. The cursor-sync plugin uses this to observe sessions without blocking any actions.

`┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Cursor Agent │────▶│ hooks.json │────▶│ cursor-sync │ │ │ │ (lifecycle │ │ (observes and │ │ - Prompts │ │ events) │ │ syncs) │ │ - Shell cmds │ │ │ │ │ │ - File edits │ └─────────────────┘ └────────┬────────┘ │ - MCP tools │ │ └─────────────────┘ ▼ ┌─────────────────┐ │ OpenSync │ │ (Convex) │ └─────────────────┘`

The hooks receive JSON payloads via stdin and can respond via stdout. cursor-sync always allows actions to proceed (it's observational, not blocking).

`Known Limitations`

Cursor CLI (cursor-agent) support is limited:

The Cursor CLI currently only fires beforeShellExecution and afterShellExecution hooks. Other events like beforeSubmitPrompt and stop only work in the Cursor IDE. This is a known limitation as of January 2026.

If you primarily use the CLI, session data will be partial. We recommend using the IDE for full session capture.

`Troubleshooting`

`$3`

`bash cursor-sync status`

`$3`

`bash cursor-sync config --json`

`$3`

`bash npm uninstall -g cursor-opensync-plugin rm -rf ~/.config/cursor-sync rm ~/.cursor/hooks.json npm install -g cursor-opensync-plugin cursor-sync login cursor-sync setup`

`$3`

If Cursor has issues after adding hooks, remove the hooks file:

`bash rm ~/.cursor/hooks.json`

Then restart Cursor and run cursor-sync setup again.

`$3`

Enable debug logging to see what's happening:

`bash cursor-sync set debug true`

Hook errors will be written to stderr.

`Development`

`bash

`Clone the repo`


git clone https://github.com/waynesutton/cursor-cli-sync-plugin
cd cursor-cli-sync-plugin
Install dependencies

npm install
Build

npm run build
Watch mode

npm run dev
Test locally

node dist/cli.js --help

License

MIT

cursor-opensync-plugin

![npm version](https://www.npmjs.com/package/cursor-opensync-plugin)
![License: MIT](https://opensource.org/licenses/MIT)

Sync your Cursor sessions to OpenSync dashboard. Track coding sessions, analyze tool usage, and monitor token consumption across projects.

GitHub: github.com/waynesutton/cursor-cli-sync-plugin

npm: npmjs.com/package/cursor-opensync-plugin

OpenSync Ecosystem

Quick Start

$3

1. Log into your OpenSync dashboard
2. Go to Settings
3. Click Generate API Key
4. Copy the key (starts with osk_)

$3

``bash cursor-sync login`

Enter when prompted:

- Convex URL: Your deployment URL (e.g., https://your-project.convex.cloud) - API Key: Your API key from Settings (e.g.,osk_abc123...)

`$3`

Option A: Use the setup command (recommended)

`bash cursor-sync setup`

This automatically configures the hooks in ~/.cursor/hooks.json.

Option B: One-liner (copy and paste)

`$3`

`bash cursor-sync verify`

You should see:

`OpenSync Setup Verification

Credentials: OK Convex URL: https://your-project.convex.cloud API Key: osk_*...*

Connection: OK

Cursor Hooks: OK Config file: ~/.cursor/hooks.json Hooks registered: cursor-sync

Ready! Start Cursor and sessions will sync automatically.`

Sessions will now sync automatically when you use Cursor.

`Installation`

`bash npm install -g cursor-opensync-plugin`

`Upgrading`

To upgrade to the latest version:

`bash npm update -g cursor-opensync-plugin`

Or reinstall the latest:

`bash npm install -g cursor-opensync-plugin@latest`

After upgrading, verify everything still works:

`bash cursor-sync --version cursor-sync verify`

If you experience issues after upgrading, re-run the setup:

`bash cursor-sync setup`

`CLI Commands`

`Hook Events`

The plugin captures these Cursor events via the hooks system:

`$3`

Set options with:

`bash cursor-sync set syncThinking true cursor-sync set debug true`

`Environment Variables`

You can also configure via environment variables:

`What Gets Synced`

`Feature Comparison`

Cursor's hooks API provides limited data compared to other CLI tools that expose session files. This table shows what each plugin can capture:

Why the difference in token/cost data?

The Cursor Analytics API and AI Code Tracking API provide aggregated team metrics but are Enterprise-only and do not expose per-session token/cost data.

`Privacy`

`How It Works`

Cursor 1.7+ introduced a hooks system that allows external scripts to run at defined stages of the agent loop. The cursor-sync plugin uses this to observe sessions without blocking any actions.

The hooks receive JSON payloads via stdin and can respond via stdout. cursor-sync always allows actions to proceed (it's observational, not blocking).

`Known Limitations`

Cursor CLI (cursor-agent) support is limited:

If you primarily use the CLI, session data will be partial. We recommend using the IDE for full session capture.

`Troubleshooting`

`$3`

`bash cursor-sync status`

`$3`

`bash cursor-sync config --json`

`$3`

`bash npm uninstall -g cursor-opensync-plugin rm -rf ~/.config/cursor-sync rm ~/.cursor/hooks.json npm install -g cursor-opensync-plugin cursor-sync login cursor-sync setup`

`$3`

If Cursor has issues after adding hooks, remove the hooks file:

`bash rm ~/.cursor/hooks.json`

Then restart Cursor and run cursor-sync setup again.

`$3`

Enable debug logging to see what's happening:

`bash cursor-sync set debug true`

Hook errors will be written to stderr.

`Development`

`bash

`Clone the repo`


git clone https://github.com/waynesutton/cursor-cli-sync-plugin
cd cursor-cli-sync-plugin
Install dependencies

npm install
Build

npm run build
Watch mode

npm run dev
Test locally

node dist/cli.js --help

License

MIT