### Clone and Setup Development Environment

Source: https://pingdotgg-t3code.mintlify.app/installation

Initial steps to clone the repository and install required dependencies using Bun.

```bash
git clone https://github.com/pingdotgg/t3code.git
cd t3code
```

```bash
# Install Bun if needed
curl -fsSL https://bun.sh/install | bash

# Install dependencies
bun install
```

--------------------------------

### Quick Start Installation

Source: https://pingdotgg-t3code.mintlify.app/

Commands to launch T3 Code via npm or download the desktop application.

```bash
npx t3
```

```bash
# Download from releases
# https://github.com/pingdotgg/t3code/releases
```

--------------------------------

### Define Setup and Installation Scripts

Source: https://pingdotgg-t3code.mintlify.app/configuration/project-scripts

Configuration for automated dependency installation and environment setup, typically set to run on worktree creation.

```json
{
  "id": "install",
  "name": "Install Dependencies",
  "command": "npm install",
  "icon": "configure",
  "runOnWorktreeCreate": true
}
```

```json
{
  "id": "setup",
  "name": "Setup Environment",
  "command": "python -m venv venv && source venv/bin/activate && pip install -r requirements.txt",
  "icon": "configure",
  "runOnWorktreeCreate": true
}
```

--------------------------------

### Starting and Resuming Sessions

Source: https://pingdotgg-t3code.mintlify.app/concepts/sessions

Examples for initializing a new session or reconnecting to an existing one.

```typescript
const session = await providerService.startSession(threadId, {
  threadId,
  provider: "codex",
  cwd: "/path/to/workspace",
  model: "gpt-5.4",
  runtimeMode: "full-access",
});
```

```typescript
const session = await providerService.startSession(threadId, {
  threadId,
  provider: "codex",
  runtimeMode: "full-access",
  resumeCursor: { threadId: "previous-thread-id" },
});
```

--------------------------------

### Start Server with Defaults

Source: https://pingdotgg-t3code.mintlify.app/configuration/server-options

Launch the server using the default configuration settings.

```bash
# Start with defaults
npx t3
```

--------------------------------

### Shell Command Examples

Source: https://pingdotgg-t3code.mintlify.app/configuration/project-scripts

Examples of valid shell commands to execute in the project workspace root.

```bash
npm test
```

```bash
bun run build
```

```bash
cargo test --all
```

```bash
python -m pytest
```

--------------------------------

### Start Production Server

Source: https://pingdotgg-t3code.mintlify.app/development/building

Launches the production server using the built artifacts.

```bash
bun run start
```

--------------------------------

### Organize Client Projects

Source: https://pingdotgg-t3code.mintlify.app/guides/project-management

Example configuration for grouping projects by client or engagement.

```bash
Project: Acme Corp - Dashboard
Project: Acme Corp - API
Project: TechStart - Mobile App
Project: Personal - Blog
```

--------------------------------

### Build Desktop App from Source

Source: https://pingdotgg-t3code.mintlify.app/installation

Commands to build desktop installers for specific platforms.

```bash
# Build arm64 DMG
bun run dist:desktop:dmg:arm64

# Build x64 DMG
bun run dist:desktop:dmg:x64
```

```bash
bun run dist:desktop:win
```

```bash
bun run dist:desktop:linux
```

--------------------------------

### GitHub CLI Installation

Source: https://pingdotgg-t3code.mintlify.app/guides/git-workflow

Commands to install the GitHub CLI on various operating systems.

```bash
# macOS
brew install gh

# Windows
winget install GitHub.cli

# Linux
sudo apt install gh
```

--------------------------------

### Install Bun

Source: https://pingdotgg-t3code.mintlify.app/development/setup

Use this command to install Bun version 1.3.9 or higher.

```bash
curl -fsSL https://bun.sh/install | bash
```

--------------------------------

### Install Node.js

Source: https://pingdotgg-t3code.mintlify.app/development/setup

Use nvm to install Node.js version 24.13.1 or higher.

```bash
# Using nvm
nvm install 24
```

--------------------------------

### Linux Debian Package Installation

Source: https://pingdotgg-t3code.mintlify.app/guides/desktop-app

Commands to install and launch the application using a .deb package.

```bash
sudo dpkg -i t3-code_*.deb
t3-code
```

--------------------------------

### Run Development Servers

Source: https://pingdotgg-t3code.mintlify.app/installation

Commands to start the web or desktop development environments.

```bash
bun run dev
```

```bash
bun run dev:desktop
```

```bash
T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop
```

--------------------------------

### Install Dependencies

Source: https://pingdotgg-t3code.mintlify.app/development/setup

Install all monorepo dependencies using Bun's workspace support.

```bash
bun install
```

--------------------------------

### Configure Basic Model

Source: https://pingdotgg-t3code.mintlify.app/api/contracts/models

Example of setting up basic model configuration and slug.

```typescript
import { CodexModelOptions, ModelSlug } from "@t3tools/contracts";

const modelConfig: CodexModelOptions = {
  reasoningEffort: "high",
  fastMode: false,
};

const modelSlug: ModelSlug = "gpt-5.4";
```

--------------------------------

### Start Development Mode

Source: https://pingdotgg-t3code.mintlify.app/development/setup

Launch the contracts builder, WebSocket server, and Vite dev server with hot reload.

```bash
bun run dev
```

--------------------------------

### Configure Monorepo Project Structure

Source: https://pingdotgg-t3code.mintlify.app/guides/project-management

Example configuration for setting up multiple projects within a monorepo structure.

```bash
# Main project
Project: my-monorepo
Root: ~/code/my-monorepo

# Sub-projects (optional)
Project: my-monorepo/web
Root: ~/code/my-monorepo/apps/web

Project: my-monorepo/api  
Root: ~/code/my-monorepo/apps/api
```

--------------------------------

### Full Persistence Setup with Effect

Source: https://pingdotgg-t3code.mintlify.app/api/server/persistence

Demonstrates how to access persistence services and run a program using dependency injection layers.

```typescript
import { Effect, Layer } from "effect";
import { layerConfig } from "./persistence/Layers/Sqlite";
import { OrchestrationEventStore } from "./persistence/Services/OrchestrationEventStore";
import { ProjectionThreadRepository } from "./persistence/Services/ProjectionThreads";
import { ServerConfig } from "./config";

const program = Effect.gen(function* () {
  // Access services
  const eventStore = yield* OrchestrationEventStore;
  const threadRepo = yield* ProjectionThreadRepository;
  
  // Read all events
  const events = yield* Stream.runCollect(eventStore.readAll());
  console.log(`Total events: ${events.length}`);
  
  // List threads for a project
  const threads = yield* threadRepo.listByProjectId({ projectId: "project-1" });
  console.log(`Threads: ${threads.length}`);
});

// Run with production persistence
const main = program.pipe(
  Effect.provide(OrchestrationEventStoreLive),
  Effect.provide(ProjectionThreadRepositoryLive),
  Effect.provide(layerConfig),
  Effect.provide(ServerConfig.layer),
);

Effect.runPromise(main);
```

--------------------------------

### Configure Frontend and Backend Projects

Source: https://pingdotgg-t3code.mintlify.app/guides/project-management

Example configuration for separating client and server projects with specific AI models.

```bash
Project: MyApp Frontend
Root: ~/code/myapp-web
Model: codex-gpt-4o

Project: MyApp Backend
Root: ~/code/myapp-api  
Model: codex-o1-preview
```

--------------------------------

### Configure Provider Model Options

Source: https://pingdotgg-t3code.mintlify.app/api/contracts/models

Example of setting up provider-specific model options.

```typescript
import { ProviderModelOptions } from "@t3tools/contracts";

const providerOptions: ProviderModelOptions = {
  codex: {
    reasoningEffort: "medium",
    fastMode: true,
  },
};
```

--------------------------------

### Script Display Name Examples

Source: https://pingdotgg-t3code.mintlify.app/configuration/project-scripts

Examples of display names for project scripts shown in the UI.

```text
Run Tests
```

```text
Build Production
```

```text
Start Dev Server
```

--------------------------------

### Install dependencies and apply patches

Source: https://pingdotgg-t3code.mintlify.app/development/setup

Run this command to install project dependencies and trigger automatic patches for the Effect language service.

```bash
# Patches are automatically applied via prepare scripts
bun install
```

--------------------------------

### Install Codex CLI

Source: https://pingdotgg-t3code.mintlify.app/installation

Follow the official installation instructions for the Codex CLI to ensure it is available on your system PATH.

```bash
# Follow installation instructions at:
# https://github.com/openai/codex
```

--------------------------------

### Build Desktop Artifacts for Linux

Source: https://pingdotgg-t3code.mintlify.app/development/building

Generates an AppImage installer for Linux x64 systems.

```bash
# AppImage (x64)
bun run dist:desktop:linux
```

--------------------------------

### Start Desktop Development

Source: https://pingdotgg-t3code.mintlify.app/development/setup

Launches the Electron desktop application, which manages its own backend process and web UI.

```bash
bun run dev:desktop
```

--------------------------------

### Dispatching Commands

Source: https://pingdotgg-t3code.mintlify.app/api/commands

Example of how to dispatch a command to the server via WebSocket.

```APIDOC
### Dispatch Example

To dispatch a command via WebSocket:

```typescript
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));
```
```

--------------------------------

### Tailscale Setup

Source: https://pingdotgg-t3code.mintlify.app/guides/cli-usage

Bind the server to a Tailnet interface for secure internal network access.

```bash
# Get your Tailnet IP
tailscale ip -4

# Bind to Tailnet interface
t3 --host 10.64.1.2 --port 8080 --auth-token secure123
```

--------------------------------

### Start the T3 Code server

Source: https://pingdotgg-t3code.mintlify.app/guides/cli-usage

Launches the server using default settings, binding to the first available port starting at 8080.

```bash
t3
```

--------------------------------

### Validate Key Syntax

Source: https://pingdotgg-t3code.mintlify.app/configuration/keybindings

Examples of valid and invalid key syntax configurations.

```json
// ❌ Invalid - empty modifiers
{ "key": "mod++", "command": "terminal.toggle" }

// ✅ Valid - trailing plus for + key
{ "key": "mod+", "command": "terminal.toggle" }
```

--------------------------------

### Auto-bootstrap projects via CLI

Source: https://pingdotgg-t3code.mintlify.app/guides/project-management

Use these commands to automatically initialize a project from the current working directory when starting the server.

```bash
# Navigate to your project
cd ~/code/my-app

# Start server (auto-bootstrap enabled by default in web mode)
t3

# Explicitly enable
t3 --auto-bootstrap-project-from-cwd

# Disable
t3 --auto-bootstrap-project-from-cwd=false
```

--------------------------------

### Build Desktop Artifacts for Windows

Source: https://pingdotgg-t3code.mintlify.app/development/building

Generates an NSIS installer for Windows x64 systems.

```bash
# NSIS installer (x64)
bun run dist:desktop:win
```

--------------------------------

### Build Custom Desktop Artifact

Source: https://pingdotgg-t3code.mintlify.app/development/building

Creates a desktop installer for a specific platform, target format, and architecture.

```bash
bun run dist:desktop:artifact -- \
  --platform mac \
  --target dmg \
  --arch arm64
```

--------------------------------

### startSession

Source: https://pingdotgg-t3code.mintlify.app/api/server/services

Starts a new provider session for a given thread.

```APIDOC
## startSession

### Description
Starts a provider session using the specified thread ID and configuration.

### Parameters
- **threadId** (ThreadId) - Required - Thread identifier
- **input** (ProviderSessionStartInput) - Required - Session configuration including provider, model, and runtime settings

### Returns
- **ProviderSession** - Active provider session details

### Errors
- **ProviderServiceError** - Thrown on adapter resolution or session startup failures
```

--------------------------------

### Verify Node.js Version

Source: https://pingdotgg-t3code.mintlify.app/installation

Check the installed Node.js version to ensure compatibility with the NPX installation method.

```bash
node --version
# Should be v22.13+, v23.4+, or v24.10+
```

--------------------------------

### Configure Production Server

Source: https://pingdotgg-t3code.mintlify.app/development/building

Starts the server with custom environment variables or command-line arguments for port, state directory, and browser behavior.

```bash
# Custom port
T3CODE_PORT=8080 bun run start

# Custom state directory
bun run start -- --state-dir ~/.t3/prod

# Don't open browser
T3CODE_NO_BROWSER=1 bun run start
```

--------------------------------

### Keybinding Precedence Example

Source: https://pingdotgg-t3code.mintlify.app/configuration/keybindings

Demonstrates how multiple rules for the same key are evaluated based on array order and context.

```json
[
  { "key": "mod+n", "command": "terminal.new", "when": "terminalFocus" },
  { "key": "mod+n", "command": "chat.new", "when": "!terminalFocus" }
]
```

--------------------------------

### Define Keybinding Rules

Source: https://pingdotgg-t3code.mintlify.app/configuration/keybindings

Example of a JSON array defining key, command, and optional conditional context for shortcuts.

```json
[
  { "key": "mod+j", "command": "terminal.toggle" },
  { "key": "mod+d", "command": "terminal.split", "when": "terminalFocus" },
  { "key": "mod+n", "command": "chat.new", "when": "!terminalFocus" }
]
```

--------------------------------

### Define Development Server Scripts

Source: https://pingdotgg-t3code.mintlify.app/configuration/project-scripts

Configuration for starting local development servers for frameworks like Next.js and Vite.

```json
{
  "id": "dev",
  "name": "Start Dev Server",
  "command": "npm run dev",
  "icon": "play",
  "runOnWorktreeCreate": false
}
```

```json
{
  "id": "dev",
  "name": "Start Dev Server",
  "command": "npm run dev",
  "icon": "play",
  "runOnWorktreeCreate": false
}
```

--------------------------------

### ProviderService.startSession

Source: https://pingdotgg-t3code.mintlify.app/concepts/sessions

Starts a new session or resumes an existing one based on the provided input parameters.

```APIDOC
## ProviderService.startSession

### Description
Initializes a session for a given thread. If a `resumeCursor` is provided, the system attempts to resume an existing thread, falling back to a fresh start if a recoverable error occurs.

### Method
`await providerService.startSession(threadId, input)`

### Parameters
- **threadId** (ThreadId) - Required - The identifier for the thread.
- **input** (ProviderSessionStartInput) - Required - Configuration object:
  - **threadId** (ThreadId) - Required
  - **provider** (string) - Optional - Defaults to "codex"
  - **cwd** (string) - Optional - Working directory
  - **model** (string) - Optional - Model identifier
  - **resumeCursor** (unknown) - Optional - Data to resume an existing thread
  - **runtimeMode** (RuntimeMode) - Required - Approval policy
  - **providerOptions** (object) - Optional - Provider-specific configuration

### Example
```typescript
const session = await providerService.startSession(threadId, {
  threadId,
  provider: "codex",
  cwd: "/path/to/workspace",
  model: "gpt-5.4",
  runtimeMode: "full-access",
});
```
```

--------------------------------

### Starting the T3 Code Server

Source: https://pingdotgg-t3code.mintlify.app/configuration/server-options

Basic commands to launch the server with specific modes, ports, or authentication tokens.

```bash
# Basic usage
npx t3

# With custom port
npx t3 --port 8080

# Desktop mode with authentication
npx t3 --mode desktop --auth-token your-secret-token
```

--------------------------------

### Debug Desktop Staging Files

Source: https://pingdotgg-t3code.mintlify.app/development/building

Builds the DMG installer while retaining staging files in the .stage/ directory for inspection.

```bash
bun run dist:desktop:dmg -- --keep-stage
```

--------------------------------

### Enable Desktop Code Signing

Source: https://pingdotgg-t3code.mintlify.app/development/building

Builds the DMG installer with code signing enabled, requiring appropriate environment variables for the target platform.

```bash
bun run dist:desktop:dmg -- --signed
```

--------------------------------

### Run Incremental Development Builds

Source: https://pingdotgg-t3code.mintlify.app/development/building

Starts a watch mode process for incremental compilation using Bun.

```bash
# Watch mode (incremental)
cd packages/contracts
bun run dev  # tsdown --watch
```

--------------------------------

### Define Testing Scripts

Source: https://pingdotgg-t3code.mintlify.app/configuration/project-scripts

Configuration examples for running test suites across different environments and languages.

```json
{
  "id": "test",
  "name": "Run Tests",
  "command": "npm test",
  "icon": "test",
  "runOnWorktreeCreate": false
}
```

```json
{
  "id": "test",
  "name": "Run Tests",
  "command": "bun test",
  "icon": "test",
  "runOnWorktreeCreate": false
}
```

```json
{
  "id": "test",
  "name": "Run Tests",
  "command": "python -m pytest",
  "icon": "test",
  "runOnWorktreeCreate": false
}
```

```json
{
  "id": "test",
  "name": "Run Tests",
  "command": "cargo test --all",
  "icon": "test",
  "runOnWorktreeCreate": false
}
```

--------------------------------

### Start the T3 Code Web Interface

Source: https://pingdotgg-t3code.mintlify.app/guides/web-interface

Commands to launch the T3 Code server with various configuration options for port, host, and browser behavior.

```bash
# Start the server (web mode is default)
t3 

# Specify a custom port
t3 --port 3000

# Bind to a specific host
t3 --host 0.0.0.0

# Disable automatic browser opening
t3 --no-browser
```

--------------------------------

### Build Desktop Artifacts for macOS

Source: https://pingdotgg-t3code.mintlify.app/development/building

Generates macOS DMG installers for specific architectures.

```bash
# ARM64 .dmg (default)
bun run dist:desktop:dmg

# Intel .dmg
bun run dist:desktop:dmg:x64

# Specific architecture
bun run dist:desktop:dmg:arm64
```

--------------------------------

### Verify T3 Code Setup

Source: https://pingdotgg-t3code.mintlify.app/quickstart

A sample prompt to test if the T3 Code environment is correctly configured and functional.

```plaintext
Create a simple hello.js file that prints "Hello from T3 Code!"
```

--------------------------------

### JSON-RPC Communication Protocol

Source: https://pingdotgg-t3code.mintlify.app/development/architecture-deep-dive

Examples of session start requests and provider event streams over stdio.

```typescript
// Start session
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session.start",
  "params": { "workspaceRoot": "/path/to/project" }
}

// Provider events stream back
{
  "jsonrpc": "2.0",
  "method": "provider.event",
  "params": { "type": "tool_invoked", ... }
}
```

--------------------------------

### GitHub Actions Build Workflow

Source: https://pingdotgg-t3code.mintlify.app/development/building

Standard CI pipeline for installing dependencies, building, typechecking, and testing.

```yaml
name: Build

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - uses: oven-sh/setup-bun@v1
        with:
          bun-version: 1.3.9
      
      - name: Install dependencies
        run: bun install
      
      - name: Build
        run: bun run build
      
      - name: Typecheck
        run: bun run typecheck
      
      - name: Test
        run: bun run test
      
      - name: Upload server artifact
        uses: actions/upload-artifact@v3
        with:
          name: t3-server
          path: apps/server/dist/
```

--------------------------------

### Define Full Stack Project Scripts

Source: https://pingdotgg-t3code.mintlify.app/configuration/project-scripts

Configuration for standard web development tasks like dependency installation, server startup, and testing.

```json
[
  {
    "id": "install",
    "name": "Install Dependencies",
    "command": "npm install",
    "icon": "configure",
    "runOnWorktreeCreate": true
  },
  {
    "id": "dev",
    "name": "Start Dev Server",
    "command": "npm run dev",
    "icon": "play",
    "runOnWorktreeCreate": false
  },
  {
    "id": "test",
    "name": "Run Tests",
    "command": "npm test",
    "icon": "test",
    "runOnWorktreeCreate": false
  },
  {
    "id": "lint",
    "name": "Lint Code",
    "command": "npm run lint",
    "icon": "lint",
    "runOnWorktreeCreate": false
  },
  {
    "id": "build",
    "name": "Build Production",
    "command": "npm run build",
    "icon": "build",
    "runOnWorktreeCreate": false
  }
]
```

--------------------------------

### Initiate Conversations with Context

Source: https://pingdotgg-t3code.mintlify.app/guides/web-interface

Examples of how to structure prompts using plain text, file references, or image attachments.

```text
How do I implement authentication in this Next.js app?
```

```text
@src/app/api/auth.ts

Can you add OAuth support to this authentication handler?
```

```text
[Attach screenshot of UI mockup]

Implement this design for the login page
```

--------------------------------

### Perform Full Production Build

Source: https://pingdotgg-t3code.mintlify.app/development/building

Executes the complete build pipeline including dependency installation, compilation, type checking, and testing.

```bash
# Clean previous builds (optional)
bun run clean

# Install dependencies
bun install

# Run full build
bun run build

# Verify with typecheck
bun run typecheck

# Run tests
bun run test
```

--------------------------------

### Start a new thread turn

Source: https://pingdotgg-t3code.mintlify.app/api/commands

Initiates a new turn with a user message and provider configuration.

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

--------------------------------

### Local Development CLI Commands

Source: https://pingdotgg-t3code.mintlify.app/guides/cli-usage

Common commands for starting the T3 Code server in a local environment.

```bash
# Default setup
t3

# With dev server
t3 --dev-url http://localhost:5173

# Custom port with logging
t3 --port 3000 --log-ws-events
```

--------------------------------

### Script Identifier Examples

Source: https://pingdotgg-t3code.mintlify.app/configuration/project-scripts

Examples of valid unique identifiers for project scripts.

```text
test
```

```text
build
```

```text
dev
```

```text
lint-fix
```

--------------------------------

### Define Keybindings with Modifiers and Special Keys

Source: https://pingdotgg-t3code.mintlify.app/configuration/keybindings

Examples of mapping commands to alphanumeric, function, navigation, and special character keys.

```json
{ "key": "mod+a", "command": "..." }
{ "key": "mod+1", "command": "..." }
```

```json
{ "key": "f1", "command": "..." }
{ "key": "f12", "command": "..." }
```

```json
{ "key": "mod+left", "command": "..." }
{ "key": "mod+right", "command": "..." }
{ "key": "mod+up", "command": "..." }
{ "key": "mod+down", "command": "..." }
```

```json
{ "key": "mod+space", "command": "..." }
{ "key": "escape", "command": "..." }
{ "key": "mod+plus", "command": "..." }
```

--------------------------------

### Initialize Desktop Backend

Source: https://pingdotgg-t3code.mintlify.app/development/building

Spawns the bundled CLI binary and establishes a WebSocket connection for the UI.

```typescript
// Spawns bundled t3 CLI on loopback with auth token
const backend = spawn(t3BinaryPath, [
  '--auth-token', token,
  '--no-browser',
]);

// UI connects via WebSocket
const wsUrl = `ws://127.0.0.1:${port}?token=${token}`;
```

--------------------------------

### Launch T3 Code via NPX

Source: https://pingdotgg-t3code.mintlify.app/quickstart

Run the T3 Code server and interface instantly without a permanent installation.

```bash
npx t3
```

--------------------------------

### Bootstrap project

Source: https://pingdotgg-t3code.mintlify.app/guides/cli-usage

Automatically initializes a project from the current working directory.

```bash
# Auto-create project from cwd
t3 --auto-bootstrap-project-from-cwd

# Default enabled in web mode, disabled in desktop mode
```

--------------------------------

### Validate Command Format

Source: https://pingdotgg-t3code.mintlify.app/configuration/keybindings

Examples of valid and invalid command formats, including script ID length limits.

```json
// ❌ Invalid - unknown command
{ "key": "mod+x", "command": "unknown.command" }

// ❌ Invalid - script ID too long
{ "key": "mod+s", "command": "script.very-long-script-id-exceeding-limit.run" }

// ✅ Valid
{ "key": "mod+t", "command": "script.test.run" }
```

--------------------------------

### OrchestrationEventStore Usage Example

Source: https://pingdotgg-t3code.mintlify.app/api/server/persistence

Demonstrates how to append an event, read all events, and replay events from a specific sequence using the OrchestrationEventStore service.

```typescript
import { Effect, Stream } from "effect";
import { OrchestrationEventStore } from "./persistence/Services/OrchestrationEventStore";

const program = Effect.gen(function* () {
  const eventStore = yield* OrchestrationEventStore;
  
  // Append an event
  const event = yield* eventStore.append({
    _tag: "OrchestrationEvent.ThreadCreated",
    commandId: "cmd-123",
    timestamp: new Date().toISOString(),
    // ... event payload
  });
  console.log(`Event persisted at sequence: ${event.sequence}`);
  
  // Read all events
  const events = yield* Stream.runCollect(eventStore.readAll());
  console.log(`Total events: ${events.length}`);
  
  // Replay from sequence 100
  yield* Stream.runForEach(
    eventStore.readFromSequence(100, 50),
    (event) => Effect.log(`Event ${event.sequence}: ${event._tag}`)
  );
});
```

--------------------------------

### Verify Codex CLI installation

Source: https://pingdotgg-t3code.mintlify.app/development/setup

Check if the Codex CLI is correctly installed and accessible in the system PATH.

```bash
which codex
codex --version
```

--------------------------------

### Conventional commit message examples

Source: https://pingdotgg-t3code.mintlify.app/guides/git-workflow

Examples of commit messages following the conventional commit format for different types of changes.

```text
feat: add user authentication

Implement OAuth2 flow with Google provider
```

```text
fix: resolve race condition in file upload

Ensure mutex lock before writing to shared buffer
```

```text
refactor: extract validation logic to separate module

Move validation from controller to middleware for reuse
```

--------------------------------

### Build for Production

Source: https://pingdotgg-t3code.mintlify.app/installation

Commands to build the server, web client, and desktop artifacts.

```bash
bun run build
bun run start
```

```bash
# Build all desktop artifacts
bun run dist:desktop:artifact

# Or specific platform:
bun run dist:desktop:dmg      # macOS DMG
bun run dist:desktop:win      # Windows installer
bun run dist:desktop:linux    # Linux AppImage
```

--------------------------------

### Initialize Application package.json

Source: https://pingdotgg-t3code.mintlify.app/development/monorepo-structure

Configuration for a new application's package.json file.

```json
{
  "name": "@t3tools/my-app",
  "version": "0.0.3",
  "private": true,
  "scripts": {
    "dev": "...",
    "build": "...",
    "typecheck": "tsc --noEmit",
    "test": "vitest run"
  },
  "dependencies": {
    "@t3tools/contracts": "workspace:*"
  },
  "devDependencies": {
    "typescript": "catalog:",
    "vitest": "catalog:"
  }
}
```

--------------------------------

### Verify T3 Code NPX installation

Source: https://pingdotgg-t3code.mintlify.app/installation

Check the installed version of the T3 Code package when using the NPX method.

```bash
npx t3 --version
# Should output: 0.0.3 (or current version)
```

--------------------------------

### Install and Authenticate Codex CLI

Source: https://pingdotgg-t3code.mintlify.app/quickstart

Prerequisites for running T3 Code, requiring the Codex CLI to be installed and authenticated on your system.

```bash
# Install Codex CLI
# Follow instructions at https://github.com/openai/codex
```

```bash
# Authenticate Codex before running T3 Code
# via API key or ChatGPT auth supported by Codex
```

--------------------------------

### thread.turn-start-requested

Source: https://pingdotgg-t3code.mintlify.app/api/events

Triggered when a user has requested to start a new turn.

```APIDOC
## thread.turn-start-requested

### Description
A user has requested to start a new turn.

### Payload Fields
- **threadId** (string) - Required
- **messageId** (string) - Required
- **provider** ('codex') - Optional - Provider to use
- **model** (string) - Optional - Model override
- **serviceTier** ('fast' | 'flex' | null) - Optional - Service tier
- **modelOptions** (object) - Optional - Provider-specific model options
- **assistantDeliveryMode** ('buffered' | 'streaming') - Optional - Delivery mode
- **runtimeMode** ('approval-required' | 'full-access') - Required
- **interactionMode** ('default' | 'plan') - Required
- **createdAt** (string) - Required
```

--------------------------------

### orchestration.replayEvents

Source: https://pingdotgg-t3code.mintlify.app/api/orchestration

Replays events starting from a specific sequence number.

```APIDOC
## orchestration.replayEvents

### Description
Replay events from a specific sequence number.
```

--------------------------------

### Create New Application Directory

Source: https://pingdotgg-t3code.mintlify.app/development/monorepo-structure

Commands to initialize the directory structure for a new application.

```bash
mkdir apps/my-app
cd apps/my-app
```

--------------------------------

### Validate When Expression

Source: https://pingdotgg-t3code.mintlify.app/configuration/keybindings

Examples of valid and invalid 'when' expression syntax.

```json
// ❌ Invalid - syntax error
{ "key": "mod+k", "command": "terminal.close", "when": "terminalFocus &&" }

// ✅ Valid
{ "key": "mod+k", "command": "terminal.close", "when": "terminalFocus" }
```

--------------------------------

### Build Web Application

Source: https://pingdotgg-t3code.mintlify.app/development/building

Commands and Vite configuration for building the React web application.

```bash
cd apps/web
bun run build
```

```typescript
import react from '@vitejs/plugin-react';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [
    react({
      babel: {
        plugins: [['babel-plugin-react-compiler', {}]],
      },
    }),
  ],
  build: {
    outDir: 'dist',
    sourcemap: true,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom'],
          router: ['@tanstack/react-router'],
        },
      },
    },
  },
});
```

--------------------------------

### ProviderSessionStartInput Interface

Source: https://pingdotgg-t3code.mintlify.app/concepts/sessions

Defines the configuration object required for starting a session.

```typescript
interface ProviderSessionStartInput {
  threadId: ThreadId;
  provider?: "codex";
  cwd?: string;                    // Working directory
  model?: string;                  // Model identifier
  resumeCursor?: unknown;          // Resume existing thread
  runtimeMode: RuntimeMode;        // Approval policy
  providerOptions?: {              // Provider-specific config
    codex?: {
      binaryPath?: string;
      homePath?: string;
    };
  };
}
```

--------------------------------

### Initialize and Configure Git Repository

Source: https://pingdotgg-t3code.mintlify.app/guides/git-workflow

Commands to initialize a repository, set user identity, and add a remote origin.

```bash
# Initialize if needed
git init

# Set user info
git config user.name "Your Name"
git config user.email "you@example.com"

# Add remote
git remote add origin https://github.com/user/repo.git
```

--------------------------------

### Resolve Model Alias

Source: https://pingdotgg-t3code.mintlify.app/api/contracts/models

Example of resolving a model alias to its actual slug.

```typescript
import { MODEL_SLUG_ALIASES_BY_PROVIDER } from "@t3tools/contracts";

const alias = "5.3";
const actualSlug = MODEL_SLUG_ALIASES_BY_PROVIDER.codex[alias];
// actualSlug === "gpt-5.3-codex"
```

--------------------------------

### Build Server Package

Source: https://pingdotgg-t3code.mintlify.app/development/building

Commands and configuration for the custom server build script.

```bash
cd apps/server
bun run build
```

```typescript
// Custom build script
// - Bundles TypeScript to ESM
// - Includes web dist as static assets
// - Generates shebang for CLI execution
```

--------------------------------

### Create a new project

Source: https://pingdotgg-t3code.mintlify.app/api/commands

Defines the structure for initializing a new project with a unique ID, title, and workspace path.

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

--------------------------------

### Clear NPX Cache

Source: https://pingdotgg-t3code.mintlify.app/installation

Clears the local npm cache for NPX installations.

```bash
npm cache clean --force
```

--------------------------------

### Initialize Server Modules

Source: https://pingdotgg-t3code.mintlify.app/development/architecture-deep-dive

Entry points and core module imports for the WebSocket server application.

```typescript
// CLI entrypoint
// Parses args, loads config, starts server
import { t3Cli } from './main';
```

```typescript
// WebSocket server and NativeApi routing
// Handles connection lifecycle, auth, RPC
import { Server } from './wsServer';
```

```typescript
// Codex app-server process management
// Session startup, resume, turn lifecycle
import { CodexAppServerManager } from './codexAppServerManager';
```

```typescript
// Provider dispatch and event coordination
// Thread logging, runtime activity projection
import { ProviderManager } from './providerManager';
```

--------------------------------

### Inline Change Summary

Source: https://pingdotgg-t3code.mintlify.app/guides/git-workflow

Example of the change summary format displayed in conversation turns.

```text
src/auth.ts        +45  -12
src/types.ts       +8   -0
tests/auth.test.ts +32  -0
```

--------------------------------

### thread.turn.start

Source: https://pingdotgg-t3code.mintlify.app/api/commands

Starts a new turn in a thread, consisting of a user message and a provider response.

```APIDOC
## thread.turn.start

### Description
Starts a new turn (user message + provider response).

### Parameters
- **type** (literal) - Required - Default: "thread.turn.start"
- **commandId** (string) - Required
- **threadId** (string) - Required
- **message** (object) - Required - User message to send
  - **messageId** (string) - Required - Message identifier (UUID)
  - **role** (literal) - Required - Default: "user"
  - **text** (string) - Required - Message content
  - **attachments** (array) - Required - Array of image attachments
- **provider** ('codex') - Optional - Provider to use
- **model** (string) - Optional - Model to use
- **serviceTier** ('fast' | 'flex' | null) - Optional - Service tier for provider
- **assistantDeliveryMode** ('buffered' | 'streaming') - Optional - Delivery mode
- **runtimeMode** ('approval-required' | 'full-access') - Required
- **interactionMode** ('default' | 'plan') - Required
- **createdAt** (string) - Required
```

--------------------------------

### Example Pull Request Description

Source: https://pingdotgg-t3code.mintlify.app/guides/git-workflow

A sample Markdown-formatted description summarizing changes and testing procedures.

```markdown
## Summary
- Implement OAuth2 authentication flow
- Add Google provider configuration  
- Create user session management
- Update API to require authentication

## Testing
Manually tested login flow with Google OAuth.
```

--------------------------------

### Example Pull Request Title

Source: https://pingdotgg-t3code.mintlify.app/guides/git-workflow

A sample title generated based on commit history or context.

```text
Add user authentication with OAuth2
```

--------------------------------

### Define Project Script Configuration

Source: https://pingdotgg-t3code.mintlify.app/guides/project-management

Example of a ProjectScript object definition used for project orchestration.

```typescript
const script: ProjectScript = {
  id: 'script_run-tests',
  name: 'Run Tests',
  command: 'npm test',
  icon: 'test',
  runOnWorktreeCreate: true,
};
```

--------------------------------

### Default Mode Request

Source: https://pingdotgg-t3code.mintlify.app/guides/web-interface

Example of a direct request for the AI to perform a task in Default Mode.

```text
Add error handling to the API routes
```

--------------------------------

### Authenticate Codex

Source: https://pingdotgg-t3code.mintlify.app/quickstart

Run the authentication command to authorize the Codex CLI before starting T3 Code.

```bash
# Use API key or ChatGPT auth supported by Codex
codex auth
```

--------------------------------

### Build Desktop Application

Source: https://pingdotgg-t3code.mintlify.app/development/building

Command to build the Electron desktop application.

```bash
cd apps/desktop
bun run build
```

--------------------------------

### Configure T3 Server via CLI

Source: https://pingdotgg-t3code.mintlify.app/api/server/configuration

Use these flags to customize server startup behavior, including mode, port, and authentication settings.

```bash
# Start in web mode with dynamic port
t3 --mode web

# Start in desktop mode with fixed port
t3 --mode desktop --port 3773

# Bind to specific interface
t3 --host 127.0.0.1

# Use custom state directory
t3 --state-dir ~/.t3code

# Development mode with Vite dev server
t3 --dev-url http://localhost:5173

# Enable authentication
t3 --auth-token my-secret-token

# Disable browser auto-open
t3 --no-browser

# Enable WebSocket event logging
t3 --log-ws-events
```

--------------------------------

### Define Effect Schema for ProviderConfig

Source: https://pingdotgg-t3code.mintlify.app/development/monorepo-structure

Example of defining a schema class using Effect/Schema for provider configuration.

```typescript
import * as S from 'effect/Schema';

export class ProviderConfig extends S.Class<ProviderConfig>('ProviderConfig')({
  providerId: S.String,
  model: S.String,
  workspaceRoot: S.String,
}) {}

export const ProviderConfigEncoded = S.encode(ProviderConfig);
export const ProviderConfigDecoded = S.decode(ProviderConfig);
```

--------------------------------

### Build desktop application

Source: https://pingdotgg-t3code.mintlify.app/development/building

Ensure contracts are built before attempting to build the desktop application.

```bash
bun run build:contracts
bun run build:desktop
```

--------------------------------

### Using ProviderService for Session and Turn Management

Source: https://pingdotgg-t3code.mintlify.app/api/server/services

Demonstrates initializing a session, sending a turn, and consuming the event stream using the Effect library.

```typescript
import { Effect, Stream } from "effect";
import { ProviderService } from "./provider/Services/ProviderService";

const program = Effect.gen(function* () {
  const provider = yield* ProviderService;
  
  // Start a session
  const session = yield* provider.startSession(threadId, {
    provider: "codex",
    model: "o3-mini",
    mode: "streaming",
    // ... other options
  });
  
  // Send a turn
  const turn = yield* provider.sendTurn({
    threadId,
    messages: [{ role: "user", content: "Hello" }],
  });
  
  // Stream events
  yield* Stream.runForEach(provider.streamEvents, (event) =>
    Effect.log(`Event: ${event._tag}`)
  );
});
```

--------------------------------

### Work with Chat Attachments

Source: https://pingdotgg-t3code.mintlify.app/api/contracts/types

Example of creating a chat image attachment object conforming to the defined schema.

```typescript
import { ChatImageAttachment } from "@t3tools/contracts";

const attachment: typeof ChatImageAttachment.Type = {
  type: "image",
  id: "img_abc123",
  name: "screenshot.png",
  mimeType: "image/png",
  sizeBytes: 1024 * 500, // 500KB
};
```

--------------------------------

### Replay Events Response

Source: https://pingdotgg-t3code.mintlify.app/api/orchestration

Example response containing an array of OrchestrationEvent objects returned by the replayEvents call.

```json
{
  "id": "req-5",
  "result": [
    {
      "sequence": 43,
      "eventId": "evt-123",
      "aggregateKind": "thread",
      "aggregateId": "thread-456",
      "type": "thread.created",
      "occurredAt": "2026-03-07T12:00:00.000Z",
      "commandId": "cmd-789",
      "causationEventId": null,
      "correlationId": "cmd-789",
      "metadata": {},
      "payload": {
        "threadId": "thread-456",
        "projectId": "proj-123",
        "title": "New thread",
        "model": "gpt-5-codex",
        "runtimeMode": "full-access",
        "interactionMode": "default",
        "createdAt": "2026-03-07T12:00:00.000Z",
        "updatedAt": "2026-03-07T12:00:00.000Z"
      }
    }
  ]
}
```

--------------------------------

### Response getSnapshot

Source: https://pingdotgg-t3code.mintlify.app/api/orchestration

Example of the JSON response returned by the getSnapshot method, containing project and thread data.

```json
{
  "id": "req-1",
  "result": {
    "snapshotSequence": 42,
    "projects": [
      {
        "id": "proj-123",
        "title": "my-app",
        "workspaceRoot": "/home/user/projects/my-app",
        "defaultModel": "gpt-5-codex",
        "scripts": [],
        "createdAt": "2026-03-07T10:00:00.000Z",
        "updatedAt": "2026-03-07T10:00:00.000Z",
        "deletedAt": null
      }
    ],
    "threads": [
      {
        "id": "thread-456",
        "projectId": "proj-123",
        "title": "New thread",
        "model": "gpt-5-codex",
        "runtimeMode": "full-access",
        "interactionMode": "default",
        "messages": [],
        "activities": [],
        "checkpoints": [],
        "session": null,
        "createdAt": "2026-03-07T10:05:00.000Z",
        "updatedAt": "2026-03-07T10:05:00.000Z",
        "deletedAt": null
      }
    ],
    "updatedAt": "2026-03-07T12:00:00.000Z"
  }
}
```

--------------------------------

### Configure runtime mode

Source: https://pingdotgg-t3code.mintlify.app/guides/cli-usage

Sets the server to either web or desktop mode, which affects security defaults and browser behavior.

```bash
# Web mode (default) - serves web UI
t3 --mode web

# Desktop mode - optimized for Electron app
t3 --mode desktop
```

--------------------------------

### Run browser tests

Source: https://pingdotgg-t3code.mintlify.app/development/testing

Installs Playwright dependencies and executes browser-based component tests for the web application.

```bash
cd apps/web

# Install Playwright (first time only)
bun run test:browser:install

# Run browser tests
bun run test:browser
```

--------------------------------

### Use Git Types

Source: https://pingdotgg-t3code.mintlify.app/api/contracts/types

Demonstrates initializing Git-related types for branches and stacked actions.

```typescript
import { GitBranch, GitStackedAction } from "@t3tools/contracts";

const branch: typeof GitBranch.Type = {
  name: "feature/new-api",
  isRemote: false,
  current: true,
  isDefault: false,
  worktreePath: null,
};

const action: GitStackedAction = "commit_push_pr";
```

--------------------------------

### Construct Server Configuration Layer

Source: https://pingdotgg-t3code.mintlify.app/api/server/configuration

Demonstrates how to create a test layer for ServerConfig and inject it into an Effect program.

```typescript
import { Layer, Effect } from "effect";
import { ServerConfig } from "./config";

// Test layer with explicit configuration
const testLayer = ServerConfig.layerTest(
  "/workspace",
  "/tmp/state"
);

// Use configuration in a program
const program = Effect.gen(function* () {
  const config = yield* ServerConfig;
  console.log(`Server running on port ${config.port}`);
  console.log(`State directory: ${config.stateDir}`);
}).pipe(Effect.provide(testLayer));
```

--------------------------------

### Codex Thread Resume Logic

Source: https://pingdotgg-t3code.mintlify.app/concepts/sessions

Internal implementation for handling thread resumption and fallback to fresh start.

```typescript
if (resumeThreadId) {
  try {
    threadOpenMethod = "thread/resume";
    threadOpenResponse = await this.sendRequest(context, "thread/resume", {
      ...sessionOverrides,
      threadId: resumeThreadId,
    });
  } catch (error) {
    if (!isRecoverableThreadResumeError(error)) {
      throw error; // Unrecoverable
    }
    
    // Fallback to fresh start
    threadOpenMethod = "thread/start";
    threadOpenResponse = await this.sendRequest(
      context,
      "thread/start",
      threadStartParams
    );
  }
}
```

--------------------------------

### Replay Events Request

Source: https://pingdotgg-t3code.mintlify.app/api/orchestration

Request structure to initiate event replay starting after the provided sequence number.

```json
{
  "id": "req-5",
  "body": {
    "_tag": "orchestration.replayEvents",
    "fromSequenceExclusive": 42
  }
}
```

--------------------------------

### Configure Desktop Server Settings

Source: https://pingdotgg-t3code.mintlify.app/guides/desktop-app

Defines the server mode, host, port, and browser behavior for the desktop application.

```json
{
  "mode": "desktop",
  "host": "127.0.0.1",
  "port": 8080,
  "noBrowser": true
}
```

--------------------------------

### Define Build Scripts

Source: https://pingdotgg-t3code.mintlify.app/configuration/project-scripts

Configuration for production and watch-mode build processes.

```json
{
  "id": "build",
  "name": "Build Production",
  "command": "npm run build",
  "icon": "build",
  "runOnWorktreeCreate": false
}
```

```json
{
  "id": "build-watch",
  "name": "Build (Watch)",
  "command": "npm run build:watch",
  "icon": "build",
  "runOnWorktreeCreate": false
}
```

--------------------------------

### Define project script keybindings

Source: https://pingdotgg-t3code.mintlify.app/configuration/keybindings

Maps keyboard shortcuts to common development workflow scripts.

```json
[
  { "key": "mod+shift+t", "command": "script.test.run" },
  { "key": "mod+shift+b", "command": "script.build.run" },
  { "key": "mod+shift+l", "command": "script.lint.run" },
  { "key": "mod+shift+d", "command": "script.dev.run" },
  { "key": "f5", "command": "script.debug.run" }
]
```

--------------------------------

### Server App Configuration and Structure

Source: https://pingdotgg-t3code.mintlify.app/development/monorepo-structure

Configuration and directory layout for the backend server application.

```json
{
  "name": "t3",
  "version": "0.0.3",
  "bin": {
    "t3": "./dist/index.mjs"
  },
  "scripts": {
    "dev": "bun run src/index.ts",
    "build": "node scripts/cli.ts build",
    "start": "node dist/index.mjs",
    "test": "vitest run"
  }
}
```

```text
Directory Structure
apps/server/
├── src/
│   ├── main.ts                    # CLI entrypoint
│   ├── wsServer.ts                # WebSocket server
│   ├── config.ts                  # Server configuration
│   ├── codexAppServerManager.ts   # Codex process management
│   ├── providerManager.ts         # Provider orchestration
│   ├── orchestration/             # Event sourcing engine
│   │   ├── Services/
│   │   ├── Layers/
│   │   ├── decider.ts
│   │   └── projector.ts
│   ├── provider/                  # Provider adapters
│   │   ├── Services/
│   │   └── Layers/
│   ├── git/                       # Git operations
│   ├── terminal/                  # Terminal management
│   ├── persistence/               # SQLite event store
│   ├── telemetry/                 # Analytics
│   └── checkpointing/             # Diff checkpointing
├── integration/                   # Integration tests
├── scripts/                       # Build scripts
└── dist/                          # Build output
```

--------------------------------

### Run Multiple Development Instances

Source: https://pingdotgg-t3code.mintlify.app/development/setup

Demonstrates how to run concurrent instances by setting the T3CODE_DEV_INSTANCE environment variable to avoid port conflicts.

```bash
# Terminal 1: Default instance
bun run dev

# Terminal 2: Feature branch instance
T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop

# Terminal 3: Another branch
T3CODE_DEV_INSTANCE=branch-a bun run dev
```