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

Build docs developers (and LLMs) love

Get started for freeTalk to us