Skip to main content

​
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: 
bun run dev:server

​
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
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

VariablePurposeDefault
T3CODE_STATE_DIRState/data directory~/.t3/dev (dev mode)
T3CODE_PORTWebSocket server port3773
T3CODE_NO_BROWSERSkip auto-opening browserfalse
T3CODE_DEV_INSTANCEInstance name for port shifting-
T3CODE_PORT_OFFSETManual port offset-
T3CODE_LOG_WS_EVENTSEnable WebSocket event loggingfalse

​
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

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
If you see TypeScript errors about missing modules:
# Rebuild contracts package
bun run build:contracts

# Clean and reinstall
bun run clean
bun install
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