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

# Development Setup

> Get your T3 Code development environment up and running

## Prerequisites

Before you begin, ensure you have the following installed:

<CardGroup cols={2}>
  <Card title="Bun" icon="cube">
    Version 1.3.9 or higher

    ```bash theme={null}
    curl -fsSL https://bun.sh/install | bash
    ```
  </Card>

  <Card title="Node.js" icon="node-js">
    Version 24.13.1 or higher

    ```bash theme={null}
    # Using nvm
    nvm install 24
    ```
  </Card>
</CardGroup>

<Warning>
  T3 Code requires **Codex CLI** to be installed and authorized to work properly.
  Install it from [github.com/openai/codex](https://github.com/openai/codex)
</Warning>

## Quick Start

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/pingdotgg/t3code.git
    cd t3code
    ```
  </Step>

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

    This will install all dependencies across the monorepo using Bun's workspace support.
  </Step>

  <Step title="Start development mode">
    ```bash theme={null}
    bun run dev
    ```

    This starts the contracts builder, WebSocket server, and Vite dev server in watch mode with hot reload.
  </Step>

  <Step title="Access the app">
    Open your browser to the URL shown in the terminal (typically `http://localhost:5733`)
  </Step>
</Steps>

## Development Modes

### Web Development

Starts the full web stack with hot reload:

```bash theme={null}
bun run dev
```

This command runs:

* `@t3tools/contracts` build in watch mode
* WebSocket server on port `3773` (configurable)
* Vite dev server on port `5733` (configurable)

<Note>
  Development mode uses `~/.t3/dev` as the state directory to keep dev state isolated from production.
</Note>

### Desktop Development

Starts the Electron desktop app:

```bash theme={null}
bun run dev:desktop
```

The desktop app spawns its own backend process and loads the web UI.

### Component-Specific Development

Run individual parts of the stack:

<CodeGroup>
  ```bash Server Only theme={null}
  bun run dev:server
  ```

  ```bash Web UI Only theme={null}
  bun run dev:web
  ```

  ```bash Marketing Site theme={null}
  bun run dev:marketing
  ```
</CodeGroup>

## Running Multiple Dev Instances

You can run multiple development instances simultaneously without port conflicts:

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

<Accordion title="How port shifting works">
  The `T3CODE_DEV_INSTANCE` environment variable hashes to a deterministic port offset:

  * Default server port: `3773`
  * Default web port: `5733`
  * Shifted ports: `base + hash(T3CODE_DEV_INSTANCE)`

  For manual control, use `T3CODE_PORT_OFFSET` with a numeric value.
</Accordion>

## Environment Variables

### Development Configuration

| Variable               | Purpose                         | Default                |
| ---------------------- | ------------------------------- | ---------------------- |
| `T3CODE_STATE_DIR`     | State/data directory            | `~/.t3/dev` (dev mode) |
| `T3CODE_PORT`          | WebSocket server port           | `3773`                 |
| `T3CODE_NO_BROWSER`    | Skip auto-opening browser       | `false`                |
| `T3CODE_DEV_INSTANCE`  | Instance name for port shifting | -                      |
| `T3CODE_PORT_OFFSET`   | Manual port offset              | -                      |
| `T3CODE_LOG_WS_EVENTS` | Enable WebSocket event logging  | `false`                |

### Turbo Configuration

These are automatically managed by the build system:

* `PORT` - Application port
* `VITE_WS_URL` - WebSocket connection URL
* `VITE_DEV_SERVER_URL` - Vite dev server URL
* `ELECTRON_RENDERER_PORT` - Electron renderer port

## Passing Server Arguments

You can pass CLI arguments to the server from root dev commands:

```bash theme={null}
# Use custom state directory
bun run dev -- --state-dir ~/.t3/another-dev-state

# Combine multiple options
bun run dev -- --state-dir /tmp/t3-test --no-browser
```

## IDE Setup

### VS Code

Recommended extensions:

```json .vscode/extensions.json theme={null}
{
  "recommendations": [
    "dbaeumer.vscode-eslint",
    "esbenp.prettier-vscode",
    "bradlc.vscode-tailwindcss"
  ]
}
```

### Effect Language Service

The project uses Effect with language service support. Run this after installing dependencies:

```bash theme={null}
# Patches are automatically applied via prepare scripts
bun install
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Port already in use">
    If you see port conflicts:

    1. Kill existing processes:
       ```bash theme={null}
       lsof -ti:3773 | xargs kill -9
       lsof -ti:5733 | xargs kill -9
       ```

    2. Or use a different instance:
       ```bash theme={null}
       T3CODE_DEV_INSTANCE=alt bun run dev
       ```
  </Accordion>

  <Accordion title="Module resolution errors">
    If you see TypeScript errors about missing modules:

    ```bash theme={null}
    # Rebuild contracts package
    bun run build:contracts

    # Clean and reinstall
    bun run clean
    bun install
    ```
  </Accordion>

  <Accordion title="Codex not found">
    Ensure Codex CLI is installed and in your PATH:

    ```bash theme={null}
    which codex
    codex --version
    ```

    If not installed, visit [github.com/openai/codex](https://github.com/openai/codex)
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="diagram-project" href="/development/architecture-deep-dive">
    Learn about the system architecture
  </Card>

  <Card title="Monorepo Structure" icon="folder-tree" href="/development/monorepo-structure">
    Understand the workspace layout
  </Card>

  <Card title="Testing" icon="flask" href="/development/testing">
    Write and run tests
  </Card>

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