# How OpenCode Implements Session Sharing: Architecture and Code Deep Dive

> Discover how OpenCode implements session sharing with its ShareNext module. Learn about REST API integration, SQLite persistence, and batched sync to Enterprise Share.

- Repository: [Anomaly/opencode](https://github.com/anomalyco/opencode)
- Tags: architecture
- Published: 2026-02-19

---

**OpenCode implements session sharing through a client-side ShareNext module that creates share records via REST API, persists metadata in SQLite, and continuously syncs session data to an Enterprise Share service using batched updates.**

The `anomalyco/opencode` repository provides a real-time, resumable session-sharing system that works across CLI, web UI, and Slack integrations. When a user initiates a share, the system generates a unique link, stores it locally, and maintains a live synchronization channel for messages, diffs, and model updates.

## Public API Interface

The sharing functionality is exposed through the `Session` class in [`packages/opencode/src/session.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/session.ts). This provides two primary methods for managing share state:

- `Session.share(sessionID)` – Initiates the sharing process by invoking `ShareNext.create`.
- `Session.unshare(sessionID)` – Terminates sharing by calling `ShareNext.remove`.

```typescript
// Create a share link
await Session.share(sessionID)

// Remove the share link
await Session.unshare(sessionID)

```

These methods serve as the entry point for all client applications, abstracting the underlying synchronization complexity.

## Client-Side Orchestration with ShareNext

The core sharing logic resides in [`packages/opencode/src/share/share-next.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/share/share-next.ts). This module handles the complete lifecycle of a shared session, from initial creation to continuous data synchronization.

### Creating Shares

The `create(sessionID)` function performs three critical operations:

1. **Server Registration**: POSTs to `/api/share` to generate a share record, receiving `{id, url, secret}`.
2. **Local Persistence**: Stores the metadata in the `session_share` SQLite table using `Database.use` with `onConflictDoUpdate` logic.
3. **Initial Sync**: Triggers `fullSync` to push the complete current session state to the server.

### Synchronization Logic

ShareNext implements an efficient delta-sync mechanism through two key functions:

- `fullSync(sessionID)` – Collects the entire session state via `Session.get`, `Session.diff`, `MessageV2.stream`, and model lists, then calls `sync()` with the complete payload.
- `sync(sessionID, data[])` – Buffers incremental updates in an in-memory queue. After a 1-second debounce period, it POSTs the batched JSON to `/api/share/{id}/sync`.

The `init()` function subscribes to internal bus events (`Session.Updated`, `MessageV2.Updated`, etc.) to automatically queue changes for synchronization without manual intervention.

### Removing Shares

The `remove(sessionID)` function reverses the creation process:

1. Retrieves the local share row from SQLite to obtain the secret.
2. Sends `DELETE /api/share/{id}` with the secret for authentication.
3. Deletes the local database row to clean up metadata.

## Local Data Persistence

Share metadata is stored locally in SQLite via the schema defined in [`packages/opencode/src/share/share.sql.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/share/share.sql.ts):

```typescript
export const SessionShareTable = sqliteTable("session_share", {
  session_id: text().primaryKey().references(() => SessionTable.id, { onDelete: "cascade" }),
  id:        text().notNull(),
  secret:    text().notNull(),
  url:       text().notNull(),
  ...Timestamps,
})

```

This table maintains the mapping between local session IDs and remote share identifiers, enabling the client to retrieve the secret required for subsequent sync and delete operations.

## Server-Side Implementation

### HTTP API Routes

The server exposes sharing endpoints in [`packages/opencode/src/server/routes/session.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/server/routes/session.ts):

| Route | Method | Description |
|-------|--------|-------------|
| `POST /:sessionID/share` | Creates a share record, returns full session object with `share_url` |
| `DELETE /:sessionID/share` | Removes the share using `Session.unshare` |
| `POST /api/share/:id/sync` | Receives batched sync data from clients |

These routes serve as thin wrappers that delegate to the Enterprise Share service for actual storage operations.

### Enterprise Share Service

The backend storage and synchronization logic is implemented in [`packages/enterprise/src/core/share.ts`](https://github.com/anomalyco/opencode/blob/main/packages/enterprise/src/core/share.ts). This service provides the following core functions:

- `create({sessionID})` – Generates a deterministic share ID from the last 8 characters of the session ID, creates a UUID secret, and stores the record under the `share/<id>` prefix in the key-value store.
- `remove({id,secret})` – Validates the secret, deletes the share record, and cleans up associated `share_data/*` entries.
- `sync({share, data})` – Verifies the secret and writes incoming batch data to `share_event/<shareID>/<timestamp>` for later compaction.
- `data(shareID)` – Retrieves compacted state and pending events, merges them using binary search-based ordering, and returns the full ordered list of `Data` objects.

The `Share.Data` type is a discriminated union supporting `session`, `message`, `part`, `session_diff`, and `model` variants, allowing the system to synchronize complex session state including code diffs and model configurations.

## Real-World Usage Examples

### CLI Integration

The OpenCode CLI supports session sharing via the `session` command in [`packages/opencode/src/cli/cmd/run.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/cli/cmd/run.ts):

```typescript
.command("session")
.option("share", { description: "Create a share link for the session", type: "boolean" })
.action(async (opts) => {
  if (opts.share) await Session.share(opts.sessionID)
})

```

### Slack Integration

The Slack bot implementation in [`packages/slack/src/index.ts`](https://github.com/anomalyco/opencode/blob/main/packages/slack/src/index.ts) demonstrates programmatic sharing:

```typescript
const shareResult = await client.session.share({ path: { id: createResult.data.id } })
if (!shareResult.error && shareResult.data) {
  console.log("🔗 Session shared:", shareResult.data.share?.url!)
}

```

### Web UI Integration

The React-based web interface handles sharing through direct SDK calls:

```typescript
// packages/web/src/pages/[...slug].md.ts
await Session.share(sessionID)
toast.success(t("toast.session.share.success.title"))

```

## Summary

- **ShareNext module** ([`packages/opencode/src/share/share-next.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/share/share-next.ts)) orchestrates client-side sharing logic, handling creation, synchronization, and removal of share links.
- **SQLite persistence** stores share metadata (ID, secret, URL) locally in the `session_share` table, enabling authenticated subsequent operations.
- **Batch synchronization** queues incremental updates with a 1-second debounce, POSTing batched JSON to `/api/share/{id}/sync` for efficient real-time collaboration.
- **Enterprise Share service** ([`packages/enterprise/src/core/share.ts`](https://github.com/anomalyco/opencode/blob/main/packages/enterprise/src/core/share.ts)) manages server-side storage using a key-value store with event sourcing (`share_event/<id>/<timestamp>`) and binary search-based merging for data retrieval.
- **Cross-platform support** enables sharing from CLI, Slack bots, and React web interfaces through the unified `Session.share` API.

## Frequently Asked Questions

### How does OpenCode handle authentication for shared sessions?

OpenCode uses a UUID-based secret system generated during share creation. When `Share.create` is called in [`packages/enterprise/src/core/share.ts`](https://github.com/anomalyco/opencode/blob/main/packages/enterprise/src/core/share.ts), it generates a unique secret that must be provided in subsequent sync and delete operations. The client stores this secret in the local SQLite `session_share` table and includes it in the Authorization header or request body when calling `/api/share/{id}/sync` or `DELETE /api/share/{id}`.

### What data types are synchronized when sharing an OpenCode session?

The system synchronizes a discriminated union of data types defined in the Enterprise Share service. According to [`packages/enterprise/src/core/share.ts`](https://github.com/anomalyco/opencode/blob/main/packages/enterprise/src/core/share.ts), the `Share.Data` type includes variants for `session` (full session state), `message` (chat messages), `part` (message components), `session_diff` (code changes), and `model` (AI model configurations). This comprehensive synchronization ensures that shared sessions maintain complete context including conversation history and code modifications.

### How does OpenCode optimize network usage during session synchronization?

OpenCode implements a batching strategy with debouncing to minimize API calls. The `ShareNext.sync` function in [`packages/opencode/src/share/share-next.ts`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/share/share-next.ts) buffers incremental updates in an in-memory queue and waits for a 1-second debounce period before sending a single batched POST request to `/api/share/{id}/sync`. Additionally, the `fullSync` operation performs an initial complete synchronization, after which only delta updates are transmitted, reducing bandwidth consumption for long-running shared sessions.

### Can shared sessions be accessed after the original client disconnects?

Yes, shared sessions persist independently of the original client connection. The Enterprise Share service in [`packages/enterprise/src/core/share.ts`](https://github.com/anomalyco/opencode/blob/main/packages/enterprise/src/core/share.ts) stores session data in a key-value store under the `share/<id>` prefix, with incremental updates written to `share_event/<shareID>/<timestamp>`. When a new viewer accesses the share URL, the `Share.data` function retrieves and compacts all stored events using binary search-based ordering, reconstructing the complete session state regardless of whether the original sharer is still online.