Skip to main content

​
Claude Code Plugin

The claude-code-sync plugin syncs your Claude Code sessions to OpenSync. It reads session data from Claude Code’s local storage and pushes it to your dashboard in real time. Source identifier: claude-code

​
Installation

Install globally with npm: 
npm install -g claude-code-sync
Or with yarn: 
yarn global add claude-code-sync
Verify the installation: 
claude-code-sync --version

​
Setup

1

Generate an API key

Log in to opensync.dev, go to Settings, and click Generate API Key. Copy the key (starts with osk_).
2

Run login

claude-code-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
3

Verify the connection

claude-code-sync status
You should see Connected: true with your Convex URL.

​
Config file

Credentials are stored in ~/.claude-code-sync/config.json: 
{
  "convexUrl": "https://polished-penguin-622.convex.cloud",
  "apiKey": "osk_..."
}

​
Commands

​
claude-code-sync login

Prompts for Convex URL and API key, then saves them to the config file.

​
claude-code-sync status

Shows connection info and sync stats: 
Connected: true
Convex URL: https://polished-penguin-622.convex.cloud
Sessions synced: 28
Last sync: 5 minutes ago

​
claude-code-sync sync

Force a manual sync of all sessions. 
claude-code-sync sync
Sessions sync automatically. Use manual sync after a network interruption or to catch any missed sessions.

​
claude-code-sync logout

Clears stored credentials. 
claude-code-sync logout

​
How syncing works

  1. Claude Code stores session data in ~/.claude/projects/ and related directories.
  2. The plugin scans for new and updated sessions.
  3. Each session is pushed to the /sync/session endpoint with source: "claude-code".
  4. Each message is pushed to /sync/message with its role, text content, token counts, and any tool call data.
  5. Deduplication uses externalId, so re-syncing is safe.

​
What gets synced

DataDescription
Conversation messagesFull history with role labels (user, assistant, system, tool)
Model infoModel name (e.g., “claude-sonnet-4-20250514”) and provider (“anthropic”)
Token countsPrompt and completion tokens per message and per session
CostEstimated cost based on Anthropic pricing
Project pathWorking directory associated with the Claude Code session
Tool callsTool names, arguments, and results

​
Session data

Each synced session maps to these database fields:
Plugin dataDatabase field
Session ID from Claudesessions.externalId
First user messagesessions.title (auto-generated)
Model namesessions.model
Input tokenssessions.promptTokens
Output tokenssessions.completionTokens
Calculated costsessions.cost
Project directorysessions.projectPath, sessions.projectName

​
Troubleshooting

​
Sessions not appearing

  1. Run claude-code-sync status to verify the connection.
  2. Check that Claude Code is active and has sessions in ~/.claude/projects/.
  3. Run claude-code-sync sync to force a manual push.

​
Duplicate sessions

Duplicates can occur if Claude Code regenerates session IDs. The plugin uses externalId for dedup, but if the source ID changes, a new session is created. Contact support if duplicates persist across syncs.

​
Authentication errors

If you see “Unauthorized” or “Invalid API key”:
  1. Check that your API key is active in the dashboard Settings.
  2. Re-run claude-code-sync login to refresh credentials.
  3. Verify the Convex URL matches your deployment.

​
Network timeouts

For slow connections, the plugin retries failed requests up to 3 times with exponential backoff. If syncs consistently fail, check your network and Convex deployment health: 
curl https://polished-penguin-622.convex.site/health

​
Updating

npm update -g claude-code-sync

​
Uninstalling

claude-code-sync logout
npm uninstall -g claude-code-sync
Synced sessions remain in your dashboard after uninstalling the plugin.