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:
Or with yarn:
Verify the installation:

​
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

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

You should see Connected: true with your Convex URL.

​
Config file

Credentials are stored in ~/.claude-code-sync/config.json:

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

​
claude-code-sync sync

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

​
claude-code-sync logout

Clears stored credentials.

​
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

​
Session data

Each synced session maps to these database fields:

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

​
Updating

​
Uninstalling

Synced sessions remain in your dashboard after uninstalling the plugin.