WebSocket Protocol

Overview

The T3 Code WebSocket API provides real-time communication between the web client and the Node.js server. The protocol uses a JSON-RPC-style request/response pattern with additional push events for server-initiated updates.

Connection

Connect to the WebSocket server at the configured port (default: 3773):

const ws = new WebSocket('ws://localhost:3773');

Authentication

If an auth token is configured, include it as a query parameter:

const ws = new WebSocket('ws://localhost:3773?token=your-auth-token');

Message Format

Request/Response Pattern

All client-initiated requests follow this structure:

string

required

Unique request identifier for matching responses

body

object

required

Request body containing the method tag and parameters

body._tag

string

required

Method name identifier (e.g., "orchestration.dispatchCommand")

Request Example

{
  "id": "req-123",
  "body": {
    "_tag": "orchestration.getSnapshot"
  }
}

Response Format

The server responds with either a success or error result:

string

required

Matches the request ID

result

unknown

The successful result data (present on success)

error

object

Error details (present on failure)

Show Error structure

message

string

Human-readable error message

Success Response Example

{
  "id": "req-123",
  "result": {
    "snapshotSequence": 42,
    "projects": [...],
    "threads": [...],
    "updatedAt": "2026-03-07T12:00:00.000Z"
  }
}

Error Response Example

{
  "id": "req-123",
  "error": {
    "message": "Thread not found"
  }
}

Push Events

The server sends push events without a corresponding request. Push events are used for real-time updates:

type

literal

default:"push"

Always "push" for server-initiated messages

channel

string

required

Event channel name (e.g., "orchestration.domainEvent")

data

unknown

required

Event payload specific to the channel

Push Event Example

{
  "type": "push",
  "channel": "orchestration.domainEvent",
  "data": {
    "sequence": 43,
    "eventId": "evt-456",
    "type": "thread.created",
    "payload": {
      "threadId": "thread-123",
      "projectId": "project-456",
      "title": "New thread",
      "model": "gpt-5.4",
      "createdAt": "2026-03-07T12:00:00.000Z"
    }
  }
}

Available Methods

The T3 Code WebSocket API exposes the following method namespaces:

Orchestration Methods

Core orchestration and command dispatch:

orchestration.getSnapshot - Get current read model snapshot
orchestration.dispatchCommand - Dispatch a client command
orchestration.getTurnDiff - Get diff for a turn range
orchestration.getFullThreadDiff - Get full thread diff
orchestration.replayEvents - Replay events from a sequence

See Orchestration API for detailed documentation.

Project Methods

Project and file operations:

projects.list - List all projects
projects.add - Add a new project
projects.remove - Remove a project
projects.searchEntries - Search project files/directories
projects.writeFile - Write content to a file

Git Methods

Version control operations:

git.status - Get repository status
git.pull - Pull changes from remote
git.listBranches - List all branches
git.createBranch - Create a new branch
git.checkout - Switch branches
git.init - Initialize a new repository
git.createWorktree - Create a git worktree
git.removeWorktree - Remove a worktree
git.runStackedAction - Execute stacked git operations (commit, push, PR)

See Git Workflow for usage examples.

Terminal Methods

Interactive terminal sessions:

terminal.open - Open a new terminal session
terminal.write - Write input to terminal
terminal.resize - Resize terminal dimensions
terminal.clear - Clear terminal output
terminal.restart - Restart a terminal session
terminal.close - Close terminal session

Shell Methods

System integration:

shell.openInEditor - Open directory in external editor

Server Methods

Server configuration and metadata:

server.getConfig - Get server configuration
server.upsertKeybinding - Update keybinding configuration

All methods are defined in packages/contracts/src/ws.ts and follow the request/response pattern described above.

Available Channels

orchestration.domainEvent

channel

Real-time orchestration events (project/thread/session updates)See Events for detailed event types.

terminal.event

channel

Terminal session output and state changes

server.welcome

channel

Initial server greeting sent on connection

Show Welcome payload

cwd

string

Current working directory

projectName

string

Inferred project name from directory

bootstrapProjectId

string

Auto-created project ID (if configured)

bootstrapThreadId

string

Auto-created thread ID (if configured)

server.configUpdated

channel

Server configuration changes (keybindings, provider status)

Protocol Schema

The WebSocket protocol is defined using Effect Schema in @t3tools/contracts:

// Source: packages/contracts/src/ws.ts

export const WebSocketRequest = Schema.Struct({
  id: TrimmedNonEmptyString,
  body: WebSocketRequestBody,
});

export const WebSocketResponse = Schema.Struct({
  id: TrimmedNonEmptyString,
  result: Schema.optional(Schema.Unknown),
  error: Schema.optional(
    Schema.Struct({
      message: Schema.String,
    }),
  ),
});

export const WsPush = Schema.Struct({
  type: Schema.Literal("push"),
  channel: TrimmedNonEmptyString,
  data: Schema.Unknown,
});

Implementation Reference

The WebSocket server implementation can be found in:

Server: apps/server/src/wsServer.ts:544-968
Contracts: packages/contracts/src/ws.ts
Client Integration: apps/web/src/api/wsClient.ts

Best Practices

Generate Unique IDs

Use UUIDs or monotonic counters for request IDs to avoid collisions

Handle Connection Loss

Implement reconnection logic with exponential backoff

Validate Schemas

Use Effect Schema for runtime validation of all messages

Subscribe to Push Events

Listen for push events immediately after connection to avoid missing updates

Error Handling

Common error scenarios:

Error	Cause	Solution
Invalid request format	Malformed JSON or schema violation	Validate against WebSocketRequest schema
Unknown method	Method name not recognized	Check available methods in WS_METHODS
Unauthorized	Missing or invalid auth token	Include valid token in connection URL
Route request error	Business logic failure	Check error.message for details

Next Steps

Orchestration API

Learn about orchestration commands and queries

Commands

Explore available command types

Events

Understand domain events

WebSocket API

Contracts

Server API

WebSocket Protocol

Overview

Connection

Authentication

Message Format

Request/Response Pattern

Request Example

Response Format

Success Response Example

Error Response Example

Push Events

Push Event Example

Available Methods

Orchestration Methods

Project Methods

Git Methods

Terminal Methods

Shell Methods

Server Methods

Available Channels

Protocol Schema

Implementation Reference

Best Practices

Generate Unique IDs

Handle Connection Loss

Validate Schemas

Subscribe to Push Events

Error Handling

Next Steps

Orchestration API

Commands

Events

Build docs developers (and LLMs) love

WebSocket API

Contracts

Server API

​Overview

​Connection

​Authentication

​Message Format

​Request/Response Pattern

​Request Example

​Response Format

​Success Response Example

​Error Response Example

​Push Events

​Push Event Example

​Available Methods

​Orchestration Methods

​Project Methods

​Git Methods

​Terminal Methods

​Shell Methods

​Server Methods

​Available Channels

​Protocol Schema

​Implementation Reference

​Best Practices

Generate Unique IDs

Handle Connection Loss

Validate Schemas

Subscribe to Push Events

​Error Handling

​Next Steps

Orchestration API

Commands

Events

Build docs developers (and LLMs) love

Overview

Connection

Authentication

Message Format

Request/Response Pattern

Request Example

Response Format

Success Response Example

Error Response Example

Push Events

Push Event Example

Available Methods

Orchestration Methods

Project Methods

Git Methods

Terminal Methods

Shell Methods

Server Methods

Available Channels

Protocol Schema

Implementation Reference

Best Practices

Error Handling

Next Steps