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

# Monorepo Structure

> Navigate the T3 Code workspace layout and understand package organization

## Workspace Overview

T3 Code uses a **Bun workspace** managed by **Turbo** for build orchestration. The monorepo is organized into apps and shared packages.

```
t3code/
├── apps/
│   ├── server/          # Node.js WebSocket server
│   ├── web/             # React + Vite UI
│   ├── desktop/         # Electron shell
│   └── marketing/       # Marketing website
├── packages/
│   ├── contracts/       # Shared schemas (Effect/Schema)
│   └── shared/          # Runtime utilities
├── scripts/             # Build and dev scripts
├── package.json         # Root workspace config
└── turbo.json          # Turbo build config
```

## Apps

### `/apps/server` - Backend Server

**Published as:** `t3` (npm package)

**Purpose:** Node.js WebSocket server that wraps Codex and manages provider sessions.

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

  ```
  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
  ```
</CodeGroup>

**Key Technologies:**

* **Runtime:** Node.js 24+
* **Effects:** Effect-TS for DI and error handling
* **Database:** @effect/sql-sqlite-bun
* **WebSocket:** ws library
* **Processes:** node-pty for terminals

**Build Output:**

* Bundled ESM: `dist/index.mjs`
* Includes web app assets (production)

### `/apps/web` - Frontend UI

**Published as:** `@t3tools/web` (workspace-only)

**Purpose:** React web application for session control and conversation rendering.

<CodeGroup>
  ```json package.json theme={null}
  {
    "name": "@t3tools/web",
    "version": "0.0.3",
    "private": true,
    "scripts": {
      "dev": "vite",
      "build": "vite build",
      "test": "vitest run --passWithNoTests",
      "test:browser": "vitest run --config vitest.browser.config.ts"
    }
  }
  ```

  ```
  Directory Structure
  apps/web/
  ├── src/
  │   ├── main.tsx                  # React entrypoint
  │   ├── store.ts                  # Global Zustand store
  │   ├── wsTransport.ts            # WebSocket client
  │   ├── wsNativeApi.ts            # NativeApi RPC client
  │   ├── routes/                   # TanStack Router routes
  │   ├── components/               # React components
  │   │   ├── ui/                   # Base UI components
  │   │   └── [features]/           # Feature components
  │   ├── lib/                      # Utilities
  │   │   ├── providerReactQuery.ts
  │   │   ├── gitReactQuery.ts
  │   │   ├── diffRendering.ts
  │   │   └── utils.ts
  │   ├── composer-logic.ts         # Composer state
  │   ├── session-logic.ts          # Session state
  │   └── keybindings.ts            # Keyboard shortcuts
  ├── public/                       # Static assets
  ├── dist/                         # Build output
  └── index.html                    # HTML entrypoint
  ```
</CodeGroup>

**Key Technologies:**

* **Framework:** React 19
* **Build Tool:** Vite 8
* **Routing:** TanStack Router
* **State:** Zustand + TanStack Query
* **Styling:** Tailwind CSS 4
* **Terminal:** xterm.js
* **Compiler:** Babel React Compiler

**Build Output:**

* Static HTML/JS/CSS in `dist/`
* Served by server in production
* Bundled in desktop app

### `/apps/desktop` - Electron App

**Published as:** `@t3tools/desktop` (workspace-only)

**Purpose:** Native desktop wrapper with auto-updates.

<CodeGroup>
  ```json package.json theme={null}
  {
    "name": "@t3tools/desktop",
    "version": "0.0.3",
    "private": true,
    "main": "dist-electron/main.js",
    "scripts": {
      "dev": "bun run --parallel dev:bundle dev:electron",
      "build": "tsdown",
      "start": "bun run scripts/start-electron.mjs",
      "smoke-test": "node scripts/smoke-test.mjs"
    },
    "productName": "T3 Code (Alpha)"
  }
  ```

  ```
  Directory Structure
  apps/desktop/
  ├── src/
  │   ├── main/                     # Electron main process
  │   │   ├── index.ts
  │   │   ├── window.ts
  │   │   └── backend.ts
  │   ├── preload/                  # Preload scripts
  │   ├── updateMachine.ts          # Auto-update state machine
  │   └── rotatingFileSink.ts       # Logging
  ├── scripts/                      # Build and dev scripts
  ├── dist-electron/                # Build output
  └── resources/                    # App icons and assets
  ```
</CodeGroup>

**Key Technologies:**

* **Platform:** Electron 40
* **Updates:** electron-updater
* **Build:** tsdown
* **Backend:** Spawns `t3` CLI

**Distribution:**

* macOS: `.dmg` (arm64/x64)
* Linux: `.AppImage`
* Windows: NSIS installer

### `/apps/marketing` - Marketing Site

**Published as:** `@t3tools/marketing` (workspace-only)

**Purpose:** Marketing and documentation website.

```json package.json theme={null}
{
  "name": "@t3tools/marketing",
  "private": true,
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}
```

## Packages

### `/packages/contracts` - Shared Schemas

**Purpose:** Effect/Schema definitions for all protocol types.

<CodeGroup>
  ```json package.json theme={null}
  {
    "name": "@t3tools/contracts",
    "version": "0.0.3",
    "private": true,
    "exports": {
      ".": {
        "types": "./src/index.ts",
        "import": "./src/index.ts",
        "require": "./dist/index.cjs"
      }
    },
    "scripts": {
      "dev": "tsdown src/index.ts --format esm,cjs --dts --watch --clean",
      "build": "tsdown src/index.ts --format esm,cjs --dts --clean"
    }
  }
  ```

  ```
  Directory Structure
  packages/contracts/
  ├── src/
  │   ├── index.ts                  # Main export
  │   ├── provider.ts               # Provider types
  │   ├── providerRuntime.ts        # Runtime events
  │   ├── orchestration.ts          # Orchestration events
  │   ├── ws.ts                     # WebSocket protocol
  │   ├── terminal.ts               # Terminal types
  │   └── keybindings.ts            # Keyboard shortcuts
  └── dist/                         # Build output
  ```
</CodeGroup>

**Schema Example:**

```typescript src/provider.ts theme={null}
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);
```

<Warning>
  Keep this package **schema-only**. No runtime logic!
</Warning>

### `/packages/shared` - Runtime Utilities

**Purpose:** Shared runtime code for server and web.

<CodeGroup>
  ```json package.json theme={null}
  {
    "name": "@t3tools/shared",
    "version": "0.0.3",
    "private": true,
    "exports": {
      "./model": "./src/model.ts",
      "./Net": "./src/Net.ts",
      "./git": "./src/git.ts"
    }
  }
  ```

  ```
  Directory Structure
  packages/shared/
  └── src/
      ├── model.ts                  # Model parsing
      ├── Net.ts                    # Network utilities
      └── git.ts                    # Git helpers
  ```
</CodeGroup>

**Subpath Exports:**

```typescript theme={null}
// Import from specific subpaths
import { parseModel } from '@t3tools/shared/model';
import { NetService } from '@t3tools/shared/Net';

// ❌ No barrel index
import { parseModel, NetService } from '@t3tools/shared';
```

## Build Scripts

### `/scripts` - Build and Dev Tooling

```
scripts/
├── dev-runner.ts                 # Dev mode orchestrator
├── build-desktop-artifact.ts     # Desktop distribution builder
├── sync-vscode-icons.mjs         # Icon asset sync
└── cli.ts                        # Server build script
```

**Key Scripts:**

| Script                      | Purpose                               |
| --------------------------- | ------------------------------------- |
| `dev-runner.ts`             | Manages Turbo watch mode and env vars |
| `build-desktop-artifact.ts` | Builds platform-specific installers   |
| `sync-vscode-icons.mjs`     | Syncs VSCode icon themes              |

## Workspace Configuration

### `package.json` (Root)

```json theme={null}
{
  "workspaces": {
    "packages": [
      "apps/*",
      "packages/*",
      "scripts"
    ],
    "catalog": {
      "effect": "https://pkg.pr.new/Effect-TS/effect-smol/effect@8881a9b",
      "typescript": "^5.7.3",
      "vitest": "^4.0.0"
    }
  },
  "engines": {
    "bun": "^1.3.9",
    "node": "^24.13.1"
  }
}
```

**Catalog Dependencies:**

Shared versions across all packages:

* `effect` - Effect-TS (smol fork)
* `typescript` - TypeScript compiler
* `vitest` - Test runner
* `@types/node` - Node.js types

### `turbo.json` - Build Pipeline

```json theme={null}
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", "dist-electron/**"]
    },
    "dev": {
      "dependsOn": ["@t3tools/contracts#build"],
      "cache": false,
      "persistent": true
    },
    "test": {
      "dependsOn": ["^build"],
      "cache": false
    }
  }
}
```

**Task Dependencies:**

* `^build` - Depends on dependencies' build tasks
* `@t3tools/contracts#build` - Contracts must build first in dev

## Dependency Graph

```mermaid theme={null}
graph TD
    Server[apps/server] --> Contracts[packages/contracts]
    Server --> Shared[packages/shared]
    Server --> Web[apps/web]
    
    Web --> Contracts
    Web --> Shared
    
    Desktop[apps/desktop] --> Contracts
    Desktop --> Shared
    Desktop --> Server
    Desktop --> Web
    
    Marketing[apps/marketing] -.->|independent| Contracts
```

**Build Order:**

1. `packages/contracts` (no dependencies)
2. `packages/shared` (no dependencies)
3. `apps/web` (depends on contracts, shared)
4. `apps/server` (depends on contracts, shared, web)
5. `apps/desktop` (depends on all)

## Adding New Packages

### Create a New App

<Steps>
  <Step title="Create directory">
    ```bash theme={null}
    mkdir apps/my-app
    cd apps/my-app
    ```
  </Step>

  <Step title="Initialize package.json">
    ```json theme={null}
    {
      "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:"
      }
    }
    ```
  </Step>

  <Step title="Add to Turbo config">
    ```json turbo.json theme={null}
    {
      "tasks": {
        "build": {
          "dependsOn": ["^build"]
        }
      }
    }
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    bun install
    ```
  </Step>
</Steps>

### Create a New Shared Package

<Steps>
  <Step title="Create directory">
    ```bash theme={null}
    mkdir packages/my-utils
    cd packages/my-utils
    ```
  </Step>

  <Step title="Initialize with subpath exports">
    ```json theme={null}
    {
      "name": "@t3tools/my-utils",
      "version": "0.0.3",
      "private": true,
      "exports": {
        "./foo": "./src/foo.ts",
        "./bar": "./src/bar.ts"
      }
    }
    ```
  </Step>

  <Step title="Add TypeScript config">
    ```json tsconfig.json theme={null}
    {
      "extends": "../../tsconfig.json",
      "compilerOptions": {
        "outDir": "./dist"
      },
      "include": ["src"]
    }
    ```
  </Step>
</Steps>

## Best Practices

<CardGroup cols={2}>
  <Card title="Shared Logic" icon="code-merge">
    Extract duplicate logic into `packages/shared` to avoid code smell
  </Card>

  <Card title="Type Safety" icon="shield">
    Use schemas from `contracts` for all cross-boundary data
  </Card>

  <Card title="Workspace Deps" icon="link">
    Always use `workspace:*` for internal dependencies
  </Card>

  <Card title="Catalog Versions" icon="book">
    Use `catalog:` for shared dependencies across packages
  </Card>
</CardGroup>

<Note>
  Long-term maintainability is a core priority. Don't be afraid to refactor!
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Testing" icon="flask" href="/development/testing">
    Learn how to write and run tests
  </Card>

  <Card title="Building" icon="hammer" href="/development/building">
    Build for production and distribution
  </Card>
</CardGroup>