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:
Or with bun:
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 ~/.opencode-sync/config.json:
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:

​
opencode-sync sync

Manually triggers a sync of all sessions. Useful after a network interruption or if you notice missing sessions.
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.

​
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

​
URL normalization

The plugin converts your Convex URL from .convex.cloud to .convex.site for HTTP endpoints:
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:

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

​
Uninstalling

Remove the plugin and its config:
This removes credentials but does not delete your synced sessions from the dashboard.