Skip to main content

​
OpenCode Plugin

The opencode-sync-plugin syncs your OpenCode sessions to OpenSync automatically. Every session, message, and token count is pushed to your dashboard in real time. Source identifier: opencode

​
Installation

Install globally with npm: 
npm install -g opencode-sync-plugin
Or with bun: 
bun install -g opencode-sync-plugin
Verify the installation: 
opencode-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

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

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

​
Config file

Credentials are stored in ~/.opencode-sync/config.json: 
{
  "convexUrl": "https://polished-penguin-622.convex.cloud",
  "apiKey": "osk_..."
}
This file is created by the login command and removed by logout.

​
Commands

​
opencode-sync login

Stores your Convex URL and API key. Prompts interactively if values are not provided as flags.

​
opencode-sync status

Shows connection state and sync statistics: 
Connected: true
Convex URL: https://polished-penguin-622.convex.cloud
Sessions synced: 42
Last sync: 2 minutes ago

​
opencode-sync sync

Manually triggers a sync of all sessions. Useful after a network interruption or if you notice missing sessions. 
opencode-sync sync
Sessions sync automatically as you work. You only need to run manual sync if something got out of step.

​
opencode-sync logout

Removes stored credentials from ~/.opencode-sync/config.json. 
opencode-sync logout

​
How syncing works

  1. OpenCode stores session data in ~/.opencode/sessions/ as JSON files.
  2. The plugin reads session and message data from this directory.
  3. Each session is pushed to the /sync/session HTTP endpoint on your Convex deployment.
  4. Each message within the session is pushed to /sync/message.
  5. The plugin uses externalId for deduplication, so re-syncing the same session is safe.

​
What gets synced

DataSourceMapped to
Session metadataOpenCode session JSONsessions table
MessagesOpenCode message entriesmessages table
Message partsText, tool calls, tool resultsparts table
Token countsPer-message and per-sessionpromptTokens, completionTokens
CostCalculated from model pricingsessions.cost
Project pathWorking directory from OpenCodesessions.projectPath
Model nameModel identifier from each messagesessions.model

​
URL normalization

The plugin converts your Convex URL from .convex.cloud to .convex.site for HTTP endpoints: 
https://polished-penguin-622.convex.cloud
  becomes
https://polished-penguin-622.convex.site
This happens automatically. You always enter the .convex.cloud URL during login.

​
Troubleshooting

​
Plugin not syncing

  1. Run opencode-sync status to check the connection.
  2. Verify your API key is still valid in the dashboard Settings.
  3. Check that OpenCode is writing to ~/.opencode/sessions/.
  4. Try opencode-sync sync to force a manual sync.

​
Sessions missing

  • OpenCode may buffer session data. Wait a few seconds after ending a session, then run opencode-sync sync.
  • Check that the session directory (~/.opencode/sessions/) contains JSON files.

​
Permission errors

The plugin needs read access to ~/.opencode/sessions/. On macOS, this is usually granted automatically. On Linux, check file permissions: 
ls -la ~/.opencode/sessions/

​
Network errors

If you see ECONNREFUSED or timeout errors:
  • Verify your Convex deployment is running (GET /health on your Convex site URL should return {"status": "ok"}).
  • Check your firewall or proxy settings.
  • For self-hosted deployments, ensure the Convex URL is correct.

​
Updating

Update to the latest version: 
npm update -g opencode-sync-plugin

​
Uninstalling

Remove the plugin and its config: 
opencode-sync logout
npm uninstall -g opencode-sync-plugin
This removes credentials but does not delete your synced sessions from the dashboard.