> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opensync.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode Plugin

> Sync sessions from OpenCode to OpenSync

# OpenCode Plugin

The `opencode-sync-plugin` syncs your [OpenCode](https://opencode.ai) 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:

```bash theme={null}
npm install -g opencode-sync-plugin
```

Or with bun:

```bash theme={null}
bun install -g opencode-sync-plugin
```

Verify the installation:

```bash theme={null}
opencode-sync --version
```

## Setup

<Steps>
  <Step title="Generate an API key">
    Log in to [opensync.dev](https://www.opensync.dev), go to **Settings**, and click **Generate API Key**. Copy the key (starts with `osk_`).
  </Step>

  <Step title="Run login">
    ```bash theme={null}
    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
  </Step>

  <Step title="Verify the connection">
    ```bash theme={null}
    opencode-sync status
    ```

    You should see `Connected: true` with your Convex URL.
  </Step>
</Steps>

## Config file

Credentials are stored in `~/.opencode-sync/config.json`:

```json theme={null}
{
  "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.

```bash theme={null}
opencode-sync sync
```

<Info>
  Sessions sync automatically as you work. You only need to run manual sync if something got out of step.
</Info>

### opencode-sync logout

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

```bash theme={null}
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

| Data             | Source                             | Mapped to                          |
| ---------------- | ---------------------------------- | ---------------------------------- |
| Session metadata | OpenCode session JSON              | `sessions` table                   |
| Messages         | OpenCode message entries           | `messages` table                   |
| Message parts    | Text, tool calls, tool results     | `parts` table                      |
| Token counts     | Per-message and per-session        | `promptTokens`, `completionTokens` |
| Cost             | Calculated from model pricing      | `sessions.cost`                    |
| Project path     | Working directory from OpenCode    | `sessions.projectPath`             |
| Model name       | Model identifier from each message | `sessions.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:

```bash theme={null}
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:

```bash theme={null}
npm update -g opencode-sync-plugin
```

## Uninstalling

Remove the plugin and its config:

```bash theme={null}
opencode-sync logout
npm uninstall -g opencode-sync-plugin
```

This removes credentials but does not delete your synced sessions from the dashboard.