Commands

Complete reference for orchestration commands

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)

---

Next Steps

Events

Learn about domain events resulting from commands

Orchestration API

Explore queries and read model