cursor-opensync-plugin

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

1. Get Your API Key

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

2. Configure the Plugin

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. Add to Cursor

Option A: Use the setup command (recommended)

cursor-sync setup

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

Option B: One-liner (copy and paste)

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

4. Verify Setup

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

npm install -g cursor-opensync-plugin

Upgrading

To upgrade to the latest version:

npm update -g cursor-opensync-plugin

Or reinstall the latest:

npm install -g cursor-opensync-plugin@latest

After upgrading, verify everything still works:

cursor-sync --version
cursor-sync verify

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

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 <key> <value> | Update a config value | | cursor-sync hook <event> | 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 |

Configuration Options

| 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:

cursor-sync set syncThinking true
cursor-sync set debug true

Environment Variables

You can also configure via environment variables:

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

Check status and connection

cursor-sync status

View current config

cursor-sync config --json

Full reset

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

Cursor won't start or shows errors

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

rm ~/.cursor/hooks.json

Then restart Cursor and run cursor-sync setup again.

Debug mode

Enable debug logging to see what's happening:

cursor-sync set debug true

Hook errors will be written to stderr.

Development

# 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

Links

OpenSync

• OpenSync - Dashboards for AI coding sessions
• OpenSync Repository

cursor-opensync-plugin (this package)

• GitHub Repository
• npm Package
• Issues and Support

Other Sync Plugins

• opencode-sync-plugin - OpenCode plugin
• claude-code-sync - Claude Code plugin
• droid-sync - Factory Droid plugin (community)
• codex-sync - Codex CLI plugin

License

MIT