opencode-remote-relay

opencode-remote-relay is a server plugin for OpenCode that forwards runtime events to a remote HTTP relay.

Install

npm i opencode-remote-relay

Configure in OpenCode

Add the plugin to your OpenCode config:

{
  "plugin": [
    [
      "opencode-remote-relay",
      {
        "url": "https://relay.example.com/ingest",
        "tokenEnv": "OPENCODE_RELAY_TOKEN",
        "include": [
          "session.created",
          "message.updated",
          "message.part.updated"
        ]
      }
    ]
  ]
}

Then set your token env var in the OpenCode process:

export OPENCODE_RELAY_TOKEN="your-token"

Options

• url (required): relay endpoint URL.
• token (optional): static bearer token.
• tokenEnv (optional, default OPENCODE_RELAY_TOKEN): env var name to read bearer token.
• include (optional): exact event type allowlist.
• exclude (optional): exact event type blocklist.
• timeoutMs (default 4000): HTTP request timeout.
• flushMs (default 200): max buffer wait before sending.
• retryMs (default 1000): delay before retry.
• maxBatch (default 50): max events per request.
• maxQueue (default 2000): in-memory queue cap.

Relay payload

Each POST sends:

{
  "events": [
    {
      "id": "uuid",
      "time": 1730000000000,
      "source": {
        "projectID": "...",
        "directory": "...",
        "worktree": "...",
        "serverUrl": "http://..."
      },
      "event": {
        "type": "message.part.updated",
        "properties": {}
      }
    }
  ]
}

Live code flow

This local setup now supports a simple pairing flow:

• Session A in OpenCode: run /live
• You get a short code (for example P7F6Z8)
• Session B in OpenCode: run /stream P7F6Z8

The relay endpoints used are:

• POST /live with { "sessionID": "..." }
• GET /pull/:code?cursor=0&waitMs=30000

For local tests:

bun run relay

Native TUI streaming

This package now ships a TUI plugin entrypoint (./tui) with native slash commands:

• /live -> creates a code for the current session (must be inside a session view)
• /stream -> opens a native streaming screen and asks for a code

The stream screen follows relay updates continuously until you exit (Esc).

V2 protocol

This package now uses a normalized relay event protocol to avoid duplicated text and unstable replay.

See V2-SPEC.md for details.

V2.2 viewer

The native stream screen now renders message cards with:

• user + assistant blocks
• model labels when available
• thinking text snapshots
• tool status lines

Interactive live mode

Host can open an interactive live room:

• /live interactive in the host session
• or /live-interactive

Viewers can send messages back to the host session:

• inside stream view: /say your message
• outside stream view: /say <CODE> your message

Notes:

• interactive mode must be enabled by the host when opening live
• viewer message is forwarded as a user prompt to the host session