Development Setup

Get your T3 Code development environment up and running

Prerequisites

Before you begin, ensure you have the following installed:

Bun

Version 1.3.9 or higher

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

Node.js

Version 24.13.1 or higher

# Using nvm
nvm install 24

T3 Code requires Codex CLI to be installed and authorized to work properly. Install it from github.com/openai/codex

Quick Start

1. Clone the repository

   git clone https://github.com/pingdotgg/t3code.git
   cd t3code
   
2. Install dependencies

   bun install
   

   This will install all dependencies across the monorepo using Bun’s workspace support.

3. Start development mode

   bun run dev
   

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

4. Access the app

   Open your browser to the URL shown in the terminal (typically http://localhost:5733)

Development Modes

Web Development

Starts the full web stack with hot reload:

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)

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

Desktop Development

Starts the Electron desktop app:

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:

Server Only

bun run dev:server

bun run dev:web

bun run dev:marketing

Running Multiple Dev Instances

You can run multiple development instances simultaneously without port conflicts:

# 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

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.

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:

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

.vscode/extensions.json

{
  "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:

# Patches are automatically applied via prepare scripts
bun install

Troubleshooting

Port already in use

If you see port conflicts:

1. Kill existing processes:

   lsof -ti:3773 | xargs kill -9
   lsof -ti:5733 | xargs kill -9
   

2. Or use a different instance:

   T3CODE_DEV_INSTANCE=alt bun run dev
   

Module resolution errors

If you see TypeScript errors about missing modules:

# Rebuild contracts package
bun run build:contracts

# Clean and reinstall
bun run clean
bun install

Codex not found

Ensure Codex CLI is installed and in your PATH:

which codex
codex --version

If not installed, visit github.com/openai/codex

Next Steps

Architecture

Learn about the system architecture

Monorepo Structure

Understand the workspace layout

Testing

Write and run tests

Building

Build for production