vibe-remote-protocol

VibeRemote binary WebSocket protocol v3 — opcode constants, encoder/decoder helpers, and TypeScript types for APP_JSON messages.

The single source of truth that lets vibe-remote-relay, the mobile client (Flutter / Dart), and the desktop agent (Electron / TypeScript) communicate over the same wire format.

한국어 README

Install

npm install vibe-remote-protocol

Quick start

import {
  OPCODE,
  encodeAppJson,
  encodeFrameSnapshotPush,
  readOpcode,
  isAppJsonMessage,
  type AppJsonMessage,
} from 'vibe-remote-protocol';

// 1) Send a hello message
const hello = encodeAppJson({ type: 'hello', protocolVersion: 3 });
ws.send(hello);

// 2) Inspect the opcode of an incoming frame
const op = readOpcode(buffer);
if (op === OPCODE.APP_JSON) {
  const json: AppJsonMessage = JSON.parse(buffer.toString('utf-8', 1));
  if (isAppJsonMessage(json, 'machine_list')) {
    console.log(json.machines);
  }
}

Opcodes

| Opcode | Name | Direction | Payload | |---|---|---|---| | 0x00 | PTY_DATA | desktop → mobile | raw PTY UTF-8 ANSI stream | | 0x01 | APP_JSON | bidirectional | UTF-8 JSON (AppJsonMessage) | | 0x02 | RESIZE | mobile → desktop | [cols u32 BE][rows u32 BE], fire-and-forget | | 0x03 | FRAME_SNAPSHOT | relay → mobile | [id len u32][id][ansi len u32][ansi] | | 0x04 | GRID_SNAPSHOT | desktop → mobile | A3 server-truth full snapshot | | 0x05 | GRID_DIFF | desktop → mobile | A3 incremental cell ops | | 0xFF | PROTOCOL_ERROR | bidirectional | [reason u8] |

0x06–0xFE are reserved.

Message types

The AppJsonMessage discriminated union includes:

• hello, hello_ack — version negotiation
• cap.req, cap.ack — A3 capability negotiation
• snapshot.req — request a fresh full grid snapshot
• machine_list, session_attach, connection_status
• terminal_data, claude_state, pty_status, git_result
• session_replay, grid_resize_capped, protocol_mismatch
• ping, pong, error, input

See dist/messages.d.ts (or src/messages.ts) for full field definitions.

Fixtures

fixtures/binary-protocol-v3.fixtures.json is the cross-validation fixture set used by all three repos (mobile / relay / desktop). Each entry contains the wire hex plus the expected parse result for one opcode. The mobile (Dart) and desktop implementations round-trip the same file.

Versioning policy

• Major — opcode added/removed or wire format change
• Minor — new AppJsonMessage type (backward compatible)
• Patch — docs / typing fixes only

Three-repo simultaneous-PR policy — see binary-protocol-v3.md §10.

For maintainers cutting a new npm release, see PUBLISHING.md.

License

MIT — see LICENSE.