Skip to content
/ cursor-cli-sync-plugin Public

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

opensync.dev/
1 star 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

waynesutton/cursor-cli-sync-plugin

BranchesTags

Repository files navigation

cursor-opensync-plugin

npm version License: 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

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.

                                           |

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

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

cursor-opensync-plugin (this package)

Other Sync Plugins

License

MIT

About

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

opensync.dev/

Topics

cli sync terminal ai opensync aicoding

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages