Skip to main content

​
OpenCode Plugin

The opencode-sync-plugin syncs your OpenCode sessions to OpenSync automatically. Supported session and message updates appear in your dashboard as the plugin syncs them. Source identifier: opencode
Hosted OpenSync uses https://api.opensync.dev for HTTP requests. The currently published OpenCode 0.3.7 login validator still requires a Convex URL. Use https://reminiscent-gull-645.convex.cloud from Settings → API Access → compatibility URL. Existing credentials remain valid.

​
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://reminiscent-gull-645.convex.cloud (for hosted) or your self-hosted URL
  • API Key: The key you copied from Settings
3

Verify the connection

Check that the saved URL and credential status match your deployment.

​
Config file

Credentials are stored in ~/.opensync/credentials.json:
This file is created by login. logout clears its saved credentials.

​
Commands

​
opencode-sync login

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

​
opencode-sync status

Shows whether credentials are configured and the saved backend URL. Use opencode-sync verify to check credentials and OpenCode plugin registration.

​
opencode-sync sync

In published version 0.3.7, plain opencode-sync sync checks connectivity and creates a test session. It does not import your session history. For the legacy JSON storage layout, use an explicit import mode:
opencode-sync sync --force clears local tracking and resends all readable sessions. Use it only when you intend to resync history.
OpenCode versions that store history in opencode.db need a compatible SQLite reader. The published 0.3.7 importer expects JSON directories; repeatedly running --force cannot fix a storage-format mismatch. Track issue #34.

​
opencode-sync logout

Clears stored credentials in ~/.opensync/credentials.json.

​
How syncing works

  1. The published reader expects legacy session JSON in ~/.local/share/opencode/storage/session/ 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 ~/.local/share/opencode/storage/session/.
  4. For legacy JSON history, use opencode-sync sync --all. For opencode.db, check the compatibility note above.

​
Sessions missing

  • Check whether your OpenCode version uses JSON storage or opencode.db before attempting an import.
  • Check that the session directory (~/.local/share/opencode/storage/session/) contains JSON files.

​
Permission errors

The plugin needs read access to ~/.local/share/opencode/storage/session/. 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.