Commands - T3 Code

Overview

Commands are the primary way to modify system state in T3 Code. Each command is validated, processed by the orchestration engine, and results in one or more domain events.

Command Structure

All commands share these base fields:

type

string

required

Command type discriminator (e.g., "project.create")

commandId

string

required

Unique command identifier (UUID)

createdAt

string

ISO 8601 timestamp (required for most commands)

Project Commands

Manage project lifecycle and metadata.

project.create

Create a new project.

type

literal

default:"project.create"

commandId

string

required

projectId

string

required

New project identifier (UUID)

title

string

required

Project display name

workspaceRoot

string

required

Absolute path to project directory

defaultModel

string

Default AI model (e.g., "gpt-5-codex")

createdAt

string

required

ISO 8601 timestamp

Example

{
  "type": "project.create",
  "commandId": "cmd-123",
  "projectId": "proj-456",
  "title": "my-app",
  "workspaceRoot": "/home/user/projects/my-app",
  "defaultModel": "gpt-5-codex",
  "createdAt": "2026-03-07T12:00:00.000Z"
}

project.meta.update

Update project metadata.

type

literal

default:"project.meta.update"

commandId

string

required

projectId

string

required

Target project identifier

title

string

New project title (optional)

workspaceRoot

string

New workspace root path (optional)

defaultModel

string

New default model (optional)

scripts

array

New project scripts array (optional)

Example

{
  "type": "project.meta.update",
  "commandId": "cmd-124",
  "projectId": "proj-456",
  "title": "my-app-renamed"
}

project.delete

Soft-delete a project.

type

literal

default:"project.delete"

commandId

string

required

projectId

string

required

Project to delete

Example

{
  "type": "project.delete",
  "commandId": "cmd-125",
  "projectId": "proj-456"
}

Thread Commands

Manage conversation threads and their lifecycle.

thread.create

Create a new conversation thread.

type

literal

default:"thread.create"

commandId

string

required

threadId

string

required

New thread identifier (UUID)

projectId

string

required

Parent project ID

title

string

required

Thread display name

model

string

required

AI model to use (e.g., "gpt-5-codex")

runtimeMode

'approval-required' | 'full-access'

required

Permission level for provider

interactionMode

'default' | 'plan'

required

Provider interaction style (default: "default")

branch

string | null

Git branch name

worktreePath

string | null

Git worktree path

createdAt

string

required

ISO 8601 timestamp

Example

{
  "type": "thread.create",
  "commandId": "cmd-126",
  "threadId": "thread-789",
  "projectId": "proj-456",
  "title": "New conversation",
  "model": "gpt-5-codex",
  "runtimeMode": "full-access",
  "interactionMode": "default",
  "branch": null,
  "worktreePath": null,
  "createdAt": "2026-03-07T12:00:00.000Z"
}

thread.delete

Soft-delete a thread.

type

literal

default:"thread.delete"

commandId

string

required

threadId

string

required

Thread to delete

thread.meta.update

Update thread metadata.

type

literal

default:"thread.meta.update"

commandId

string

required

threadId

string

required

title

string

New title (optional)

model

string

New model (optional)

branch

string | null

New branch (optional)

worktreePath

string | null

New worktree path (optional)

thread.runtime-mode.set

Change thread runtime permission mode.

type

literal

default:"thread.runtime-mode.set"

commandId

string

required

threadId

string

required

runtimeMode

'approval-required' | 'full-access'

required

New runtime mode

createdAt

string

required

Runtime Modes

approval-required

Provider must request approval for file changes and commands

full-access

Provider can execute file changes and commands without approval

thread.interaction-mode.set

Change thread interaction style.

type

literal

default:"thread.interaction-mode.set"

commandId

string

required

threadId

string

required

interactionMode

'default' | 'plan'

required

New interaction mode

createdAt

string

required

Interaction Modes

default

Standard back-and-forth conversation with immediate execution

plan

Provider proposes a plan before execution (Codex-specific)

thread.turn.start

Start a new turn (user message + provider response).

type

literal

default:"thread.turn.start"

commandId

string

required

threadId

string

required

message

object

required

User message to send

Show Message structure

messageId

string

required

Message identifier (UUID)

role

literal

default:"user"

Always "user" for turn start

text

string

required

Message content

attachments

array

required

Array of image attachments (base64 data URLs from client, persisted attachments from server)

provider

'codex'

Provider to use (optional, defaults to project default)

model

string

Model to use (optional)

serviceTier

'fast' | 'flex' | null

Service tier for provider (optional)

assistantDeliveryMode

'buffered' | 'streaming'

How to deliver assistant messages (optional)

runtimeMode

'approval-required' | 'full-access'

required

Runtime mode for this turn

interactionMode

'default' | 'plan'

required

Interaction mode for this turn

createdAt

string

required

Example

{
  "type": "thread.turn.start",
  "commandId": "cmd-127",
  "threadId": "thread-789",
  "message": {
    "messageId": "msg-abc",
    "role": "user",
    "text": "Add a health check endpoint",
    "attachments": []
  },
  "runtimeMode": "full-access",
  "interactionMode": "default",
  "createdAt": "2026-03-07T12:05:00.000Z"
}

The client sends attachments as base64 data URLs. The server persists them and converts to attachment references.

thread.turn.interrupt

Interrupt the currently running turn.

type

literal

default:"thread.turn.interrupt"

commandId

string

required

threadId

string

required

turnId

string

Specific turn to interrupt (optional, defaults to active turn)

createdAt

string

required

Example

{
  "type": "thread.turn.interrupt",
  "commandId": "cmd-128",
  "threadId": "thread-789",
  "createdAt": "2026-03-07T12:06:00.000Z"
}

thread.approval.respond

Respond to a provider approval request.

type

literal

default:"thread.approval.respond"

commandId

string

required

threadId

string

required

requestId

string

required

Approval request identifier

decision

'accept' | 'acceptForSession' | 'decline' | 'cancel'

required

User’s approval decision

createdAt

string

required

Approval Decisions

accept

Approve this specific action

acceptForSession

Approve this action and all similar ones for the session

decline

Reject this action

cancel

Cancel the entire turn

thread.user-input.respond

Respond to a provider user input request.

type

literal

default:"thread.user-input.respond"

commandId

string

required

threadId

string

required

requestId

string

required

User input request identifier

answers

object

required

Key-value map of answers to provider questions

createdAt

string

required

thread.checkpoint.revert

Revert the thread to a previous checkpoint.

type

literal

default:"thread.checkpoint.revert"

commandId

string

required

threadId

string

required

turnCount

number

required

Number of turns to revert (from end)

createdAt

string

required

Example

{
  "type": "thread.checkpoint.revert",
  "commandId": "cmd-129",
  "threadId": "thread-789",
  "turnCount": 2,
  "createdAt": "2026-03-07T12:10:00.000Z"
}

Reverting checkpoints modifies git history. Use with caution.

thread.session.stop

Stop the active provider session for a thread.

type

literal

default:"thread.session.stop"

commandId

string

required

threadId

string

required

createdAt

string

required

Internal Commands

These commands are dispatched by the server internally and are not available to clients:

thread.session.set - Update session state
thread.message.assistant.delta - Append streaming assistant message chunk
thread.message.assistant.complete - Mark assistant message complete
thread.proposed-plan.upsert - Update proposed plan
thread.turn.diff.complete - Record turn checkpoint
thread.activity.append - Add activity log entry
thread.revert.complete - Confirm checkpoint revert

Dispatch Example

To dispatch a command via WebSocket:

const command = {
  type: 'project.create',
  commandId: crypto.randomUUID(),
  projectId: crypto.randomUUID(),
  title: 'My New Project',
  workspaceRoot: '/home/user/projects/my-project',
  defaultModel: 'gpt-5-codex',
  createdAt: new Date().toISOString(),
};

const request = {
  id: crypto.randomUUID(),
  body: {
    _tag: 'orchestration.dispatchCommand',
    command,
  },
};

ws.send(JSON.stringify(request));

Source Code

Command schemas are defined in:

Contracts: packages/contracts/src/orchestration.ts:281-555
Command Handler: apps/server/src/orchestration/commandHandlers.ts
Dispatch Route: apps/server/src/wsServer.ts:688-692

Validation

All commands are validated using Effect Schema:

String IDs are trimmed and checked for non-empty
Timestamps are validated as ISO 8601
Enum fields are checked against allowed values
Image attachments are size-limited (10MB max)
Turn count ranges are validated (fromTurnCount ≤ toTurnCount)

WebSocket API

Contracts

Server API

​Overview

​Command Structure

​Project Commands

​project.create

​Example

​project.meta.update

​Example

​project.delete

​Example

​Thread Commands

​thread.create

​Example

​thread.delete

​thread.meta.update

​thread.runtime-mode.set

​Runtime Modes

approval-required

full-access

​thread.interaction-mode.set

​Interaction Modes

default

plan

​thread.turn.start

​Example

​thread.turn.interrupt

​Example

​thread.approval.respond

​Approval Decisions

accept

acceptForSession

decline

cancel

​thread.user-input.respond

​thread.checkpoint.revert

​Example

​thread.session.stop

​Internal Commands

​Dispatch Example

​Source Code

​Validation

​Next Steps

Events

Orchestration API

Build docs developers (and LLMs) love

Overview

Command Structure

Project Commands

project.create

Example

project.meta.update

Example

project.delete

Example

Thread Commands

thread.create

Example

thread.delete

thread.meta.update

thread.runtime-mode.set

Runtime Modes

thread.interaction-mode.set

Interaction Modes

thread.turn.start

Example

thread.turn.interrupt

Example

thread.approval.respond

Approval Decisions

thread.user-input.respond

thread.checkpoint.revert

Example

thread.session.stop

Internal Commands

Dispatch Example

Source Code

Validation

Next Steps