> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pingdotgg/t3code/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<ParamField path="type" type="string" required>
  Command type discriminator (e.g., `"project.create"`)
</ParamField>

<ParamField path="commandId" type="string" required>
  Unique command identifier (UUID)
</ParamField>

<ParamField path="createdAt" type="string">
  ISO 8601 timestamp (required for most commands)
</ParamField>

***

## Project Commands

Manage project lifecycle and metadata.

### project.create

Create a new project.

<ParamField path="type" type="literal" default="project.create" />

<ParamField path="commandId" type="string" required />

<ParamField path="projectId" type="string" required>
  New project identifier (UUID)
</ParamField>

<ParamField path="title" type="string" required>
  Project display name
</ParamField>

<ParamField path="workspaceRoot" type="string" required>
  Absolute path to project directory
</ParamField>

<ParamField path="defaultModel" type="string">
  Default AI model (e.g., `"gpt-5-codex"`)
</ParamField>

<ParamField path="createdAt" type="string" required>
  ISO 8601 timestamp
</ParamField>

#### Example

```json theme={null}
{
  "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.

<ParamField path="type" type="literal" default="project.meta.update" />

<ParamField path="commandId" type="string" required />

<ParamField path="projectId" type="string" required>
  Target project identifier
</ParamField>

<ParamField path="title" type="string">
  New project title (optional)
</ParamField>

<ParamField path="workspaceRoot" type="string">
  New workspace root path (optional)
</ParamField>

<ParamField path="defaultModel" type="string">
  New default model (optional)
</ParamField>

<ParamField path="scripts" type="array">
  New project scripts array (optional)
</ParamField>

#### Example

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

***

### project.delete

Soft-delete a project.

<ParamField path="type" type="literal" default="project.delete" />

<ParamField path="commandId" type="string" required />

<ParamField path="projectId" type="string" required>
  Project to delete
</ParamField>

#### Example

```json theme={null}
{
  "type": "project.delete",
  "commandId": "cmd-125",
  "projectId": "proj-456"
}
```

***

## Thread Commands

Manage conversation threads and their lifecycle.

### thread.create

Create a new conversation thread.

<ParamField path="type" type="literal" default="thread.create" />

<ParamField path="commandId" type="string" required />

<ParamField path="threadId" type="string" required>
  New thread identifier (UUID)
</ParamField>

<ParamField path="projectId" type="string" required>
  Parent project ID
</ParamField>

<ParamField path="title" type="string" required>
  Thread display name
</ParamField>

<ParamField path="model" type="string" required>
  AI model to use (e.g., `"gpt-5-codex"`)
</ParamField>

<ParamField path="runtimeMode" type="'approval-required' | 'full-access'" required>
  Permission level for provider
</ParamField>

<ParamField path="interactionMode" type="'default' | 'plan'" required>
  Provider interaction style (default: `"default"`)
</ParamField>

<ParamField path="branch" type="string | null">
  Git branch name
</ParamField>

<ParamField path="worktreePath" type="string | null">
  Git worktree path
</ParamField>

<ParamField path="createdAt" type="string" required>
  ISO 8601 timestamp
</ParamField>

#### Example

```json theme={null}
{
  "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.

<ParamField path="type" type="literal" default="thread.delete" />

<ParamField path="commandId" type="string" required />

<ParamField path="threadId" type="string" required>
  Thread to delete
</ParamField>

***

### thread.meta.update

Update thread metadata.

<ParamField path="type" type="literal" default="thread.meta.update" />

<ParamField path="commandId" type="string" required />

<ParamField path="threadId" type="string" required />

<ParamField path="title" type="string">
  New title (optional)
</ParamField>

<ParamField path="model" type="string">
  New model (optional)
</ParamField>

<ParamField path="branch" type="string | null">
  New branch (optional)
</ParamField>

<ParamField path="worktreePath" type="string | null">
  New worktree path (optional)
</ParamField>

***

### thread.runtime-mode.set

Change thread runtime permission mode.

<ParamField path="type" type="literal" default="thread.runtime-mode.set" />

<ParamField path="commandId" type="string" required />

<ParamField path="threadId" type="string" required />

<ParamField path="runtimeMode" type="'approval-required' | 'full-access'" required>
  New runtime mode
</ParamField>

<ParamField path="createdAt" type="string" required />

#### Runtime Modes

<Card title="approval-required" icon="shield">
  Provider must request approval for file changes and commands
</Card>

<Card title="full-access" icon="unlock">
  Provider can execute file changes and commands without approval
</Card>

***

### thread.interaction-mode.set

Change thread interaction style.

<ParamField path="type" type="literal" default="thread.interaction-mode.set" />

<ParamField path="commandId" type="string" required />

<ParamField path="threadId" type="string" required />

<ParamField path="interactionMode" type="'default' | 'plan'" required>
  New interaction mode
</ParamField>

<ParamField path="createdAt" type="string" required />

#### Interaction Modes

<Card title="default" icon="comments">
  Standard back-and-forth conversation with immediate execution
</Card>

<Card title="plan" icon="list-check">
  Provider proposes a plan before execution (Codex-specific)
</Card>

***

### thread.turn.start

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

<ParamField path="type" type="literal" default="thread.turn.start" />

<ParamField path="commandId" type="string" required />

<ParamField path="threadId" type="string" required />

<ParamField path="message" type="object" required>
  User message to send

  <Expandable title="Message structure">
    <ParamField path="messageId" type="string" required>
      Message identifier (UUID)
    </ParamField>

    <ParamField path="role" type="literal" default="user">
      Always `"user"` for turn start
    </ParamField>

    <ParamField path="text" type="string" required>
      Message content
    </ParamField>

    <ParamField path="attachments" type="array" required>
      Array of image attachments (base64 data URLs from client, persisted attachments from server)
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="provider" type="'codex'">
  Provider to use (optional, defaults to project default)
</ParamField>

<ParamField path="model" type="string">
  Model to use (optional)
</ParamField>

<ParamField path="serviceTier" type="'fast' | 'flex' | null">
  Service tier for provider (optional)
</ParamField>

<ParamField path="assistantDeliveryMode" type="'buffered' | 'streaming'">
  How to deliver assistant messages (optional)
</ParamField>

<ParamField path="runtimeMode" type="'approval-required' | 'full-access'" required>
  Runtime mode for this turn
</ParamField>

<ParamField path="interactionMode" type="'default' | 'plan'" required>
  Interaction mode for this turn
</ParamField>

<ParamField path="createdAt" type="string" required />

#### Example

```json theme={null}
{
  "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"
}
```

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

***

### thread.turn.interrupt

Interrupt the currently running turn.

<ParamField path="type" type="literal" default="thread.turn.interrupt" />

<ParamField path="commandId" type="string" required />

<ParamField path="threadId" type="string" required />

<ParamField path="turnId" type="string">
  Specific turn to interrupt (optional, defaults to active turn)
</ParamField>

<ParamField path="createdAt" type="string" required />

#### Example

```json theme={null}
{
  "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.

<ParamField path="type" type="literal" default="thread.approval.respond" />

<ParamField path="commandId" type="string" required />

<ParamField path="threadId" type="string" required />

<ParamField path="requestId" type="string" required>
  Approval request identifier
</ParamField>

<ParamField path="decision" type="'accept' | 'acceptForSession' | 'decline' | 'cancel'" required>
  User's approval decision
</ParamField>

<ParamField path="createdAt" type="string" required />

#### Approval Decisions

<Card title="accept" icon="check">
  Approve this specific action
</Card>

<Card title="acceptForSession" icon="shield-check">
  Approve this action and all similar ones for the session
</Card>

<Card title="decline" icon="xmark">
  Reject this action
</Card>

<Card title="cancel" icon="ban">
  Cancel the entire turn
</Card>

***

### thread.user-input.respond

Respond to a provider user input request.

<ParamField path="type" type="literal" default="thread.user-input.respond" />

<ParamField path="commandId" type="string" required />

<ParamField path="threadId" type="string" required />

<ParamField path="requestId" type="string" required>
  User input request identifier
</ParamField>

<ParamField path="answers" type="object" required>
  Key-value map of answers to provider questions
</ParamField>

<ParamField path="createdAt" type="string" required />

***

### thread.checkpoint.revert

Revert the thread to a previous checkpoint.

<ParamField path="type" type="literal" default="thread.checkpoint.revert" />

<ParamField path="commandId" type="string" required />

<ParamField path="threadId" type="string" required />

<ParamField path="turnCount" type="number" required>
  Number of turns to revert (from end)
</ParamField>

<ParamField path="createdAt" type="string" required />

#### Example

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

<Warning>
  Reverting checkpoints modifies git history. Use with caution.
</Warning>

***

### thread.session.stop

Stop the active provider session for a thread.

<ParamField path="type" type="literal" default="thread.session.stop" />

<ParamField path="commandId" type="string" required />

<ParamField path="threadId" type="string" required />

<ParamField path="createdAt" type="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:

```typescript theme={null}
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

<CardGroup cols={2}>
  <Card title="Events" icon="bolt" href="/api/events">
    Learn about domain events resulting from commands
  </Card>

  <Card title="Orchestration API" icon="diagram-project" href="/api/orchestration">
    Explore queries and read model
  </Card>
</CardGroup>