opencode-sync-plugin

Sync your OpenCode sessions to the cloud. Search, share, and access your coding history from anywhere.

OpenSync Ecosystem

| Project | Description | Links | | ---------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | OpenSync | Dashboards for AI coding sessions | Website / GitHub | | opencode-sync-plugin | Sync OpenCode sessions | GitHub / npm | | claude-code-sync | Sync Claude Code sessions | GitHub / npm | | droid-sync | Sync Factory Droid sessions (community built) | GitHub / npm | | codex-sync | Sync Codex CLI sessions | GitHub / npm | | cursor-opensync-plugin | Sync Cursor sessions | GitHub / npm |

Installation

From npm

Published on npm: opencode-sync-plugin

npm install -g opencode-sync-plugin

From source

git clone https://github.com/waynesutton/opencode-sync-plugin
cd opencode-sync-plugin
npm install
npm run build

Upgrading

To upgrade to the latest version of the plugin:

Using npm:

npm update -g opencode-sync-plugin

Or reinstall to get the latest:

npm install -g opencode-sync-plugin@latest

Clear the OpenCode plugin cache (required for OpenCode to pick up the new version):

rm -rf ~/.cache/opencode/node_modules/opencode-sync-plugin

Restart OpenCode to load the updated plugin.

Check your installed version:

opencode-sync version

Backfill existing sessions with proper titles (if upgrading from v0.3.2 or earlier):

opencode-sync sync --force

This re-syncs all local sessions with accurate titles from OpenCode's local storage.

Setup

1. Get your credentials

You need two things from your OpenSync deployment

• Convex URL: Your deployment URL from the Convex dashboard (e.g., https://your-project-123.convex.cloud)
• API Key: Generated in the OpenSync dashboard at Settings > API Key (starts with osk_)

The plugin automatically converts the .cloud URL to .site for API calls.

2. Configure the plugin

opencode-sync login

Follow the prompts:

1. Enter your Convex URL
2. Enter your API Key

No browser authentication required.

3. Add to OpenCode

Quick setup (global config, works for all projects):

mkdir -p ~/.config/opencode && echo '{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-sync-plugin"]
}' > ~/.config/opencode/opencode.json

Or manually add to your opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-sync-plugin"]
}

Config locations:

• Global: ~/.config/opencode/opencode.json (applies to all projects)
• Per-project: ./opencode.json in your project root

Note: If you already have an opencode.json with other settings, edit the file manually and add "plugin": ["opencode-sync-plugin"] to preserve your existing configuration. OpenCode merges configs, so you can keep your theme, model, and other settings.

4. Verify installation

opencode-sync verify

This checks that both your credentials and OpenCode config are set up correctly. You should see:

  OpenSync Setup Verification

  Credentials: OK
  Convex URL: https://your-project.convex.cloud
  API Key: osk_****...****

  OpenCode Config: OK
  Config file: ~/.config/opencode/opencode.json
  Plugin registered: opencode-sync-plugin

  Ready! Start OpenCode and the plugin will load automatically.

How it works

The plugin hooks into OpenCode events and syncs data automatically:

| Event | Action | | ---------------------- | ------------------------------------------------------ | | session.created | Creates session record in cloud | | session.updated | Updates session metadata | | session.idle | Final sync with accurate title, token counts, and cost | | message.updated | Syncs user and assistant messages | | message.part.updated | Syncs completed message parts |

On session.idle, the plugin queries OpenCode's SDK to get the accurate session title (generated after the first message exchange). This ensures sessions are stored with meaningful titles instead of "Untitled".

Data is stored in your Convex deployment. You can view, search, and share sessions via the web UI.

CLI Commands

| Command | Description | | ---------------------------- | --------------------------------------------------- | | opencode-sync login | Configure with Convex URL and API Key | | opencode-sync verify | Verify credentials and OpenCode config | | opencode-sync sync | Test connectivity and create a test session | | opencode-sync sync --new | Sync only new sessions (uses local tracking) | | opencode-sync sync --all | Sync all sessions (queries backend, skips existing) | | opencode-sync sync --force | Clear tracking and resync all sessions | | opencode-sync logout | Clear stored credentials | | opencode-sync status | Show authentication status | | opencode-sync config | Show current configuration | | opencode-sync version | Show installed version | | opencode-sync help | Show help message |

Configuration storage

Credentials are stored at:

~/.config/opencode-sync/
  config.json       # Convex URL, API Key

Plugin architecture

This plugin follows the OpenCode plugin specification:

import type { Plugin } from "@opencode-ai/plugin";

export const OpenCodeSyncPlugin: Plugin = async ({
  project,
  client,
  $,
  directory,
  worktree,
}) => {
  // Initialize plugin
  await client.app.log({
    service: "opencode-sync",
    level: "info",
    message: "Plugin initialized",
  });

  return {
    // Subscribe to events
    event: async ({ event }) => {
      if (event.type === "session.created") {
        // Sync session to cloud
      }
      if (event.type === "message.updated") {
        // Sync message to cloud
      }
    },
  };
};

This plugin exports both a named and default export so OpenCode can load it from npm reliably.

Troubleshooting

Having issues? Open an issue on GitHub and we'll help you out.

OpenCode won't start or shows blank screen

If OpenCode hangs or shows a blank screen after adding the plugin, remove the plugin config:

Step 1: Open a new terminal window

Step 2: Remove the plugin from your config

# Option A: Delete the entire config (if you only have the plugin configured)
rm ~/.config/opencode/opencode.json

# Option B: Edit the file to remove the plugin line
nano ~/.config/opencode/opencode.json
# Remove the "plugin": ["opencode-sync-plugin"] line and save

Step 3: Clear the plugin cache

rm -rf ~/.cache/opencode/node_modules/opencode-sync-plugin

Step 4: Restart OpenCode

opencode

If the issue persists, reinstall the latest version and clear the cache again.

"Not authenticated" errors

opencode-sync login

Invalid API Key

1. Go to your OpenSync dashboard
2. Navigate to Settings
3. Generate a new API Key
4. Run opencode-sync login with the new key

Check status

opencode-sync status

View logs

Plugin logs are available in OpenCode's log output. Look for entries with service: "opencode-sync".

Still having issues?

If none of the above solutions work, open an issue with details about your setup and the error you're seeing.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

Links

• OpenSync Dashboard
• OpenSync GitHub
• opencode-sync-plugin npm
• claude-code-sync npm
• Report Issues

License

MIT