Skip to main content

​
Prerequisites

Before installing T3 Code, ensure you have the required dependencies.

​
Codex CLI (Required)

T3 Code requires Codex CLI to be installed and authenticated. This is not optional.
T3 Code is currently Codex-first and wraps the Codex app server:
1

Install Codex CLI

Install the Codex CLI so that codex is available on your PATH:
# Follow installation instructions at:
# https://github.com/openai/codex
Verify installation:
codex --version
2

Authenticate Codex

Authenticate Codex before running T3 Code:
# Use API key or ChatGPT auth supported by Codex
codex auth
T3 Code starts the server via codex app-server per session, so authentication must be completed beforehand.

​
Runtime Requirements

Node.js: Version 22.13+, 23.4+, or 24.10+
node --version
# Should be v22.13+, v23.4+, or v24.10+
The NPX method will use your system Node.js to run the server.

​
Installation Methods

The fastest way to run T3 Code without installation: 
npx t3
What this does:
  • Downloads the latest published version from npm
  • Starts the Node.js WebSocket server
  • Serves the React web interface
  • Opens http://localhost:3773 in your browser
  • Connects via ws://localhost:3773
Use NPX when you want to:
  • Try T3 Code without committing to an installation
  • Always run the latest version
  • Use T3 Code occasionally from any directory
Package details: 
{
  "name": "t3",
  "version": "0.0.3",
  "bin": {
    "t3": "./dist/index.mjs"
  }
}

​
Desktop Application

For a native experience with better system integration:
1

Download the installer

Visit the GitHub Releases page and download for your platform:
Download: .dmg fileAvailable architectures:
  • arm64 (Apple Silicon: M1, M2, M3)
  • x64 (Intel Macs)
Build from source
# Build arm64 DMG
bun run dist:desktop:dmg:arm64

# Build x64 DMG
bun run dist:desktop:dmg:x64
2

Install the application

  1. Open the downloaded .dmg file
  2. Drag T3 Code to your Applications folder
  3. Launch from Applications or Spotlight
On first launch, you may need to allow the app in System Settings → Privacy & Security
3

Launch and verify

Open the T3 Code desktop app. It should:
  • Start the embedded server
  • Load the web interface in the Electron window
  • Connect to the WebSocket server
  • Be ready to create your first session
If the interface loads and you can access the chat, installation is complete!

​
Development Installation

For contributors and developers working on T3 Code itself:
This method is for T3 Code development only, not for end users.
1

Clone the repository

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

Install dependencies

T3 Code uses Bun as the package manager:
# Install Bun if needed
curl -fsSL https://bun.sh/install | bash

# Install dependencies
bun install
Required versions:
  • Bun: 1.3.9+
  • Node: 24.13.1+ (for runtime)
3

Run development server

Run with hot reload:
bun run dev
This starts:
  • Server at localhost:3773
  • Web client with Vite HMR
4

Build for production

bun run build
bun run start

​
Architecture Overview

Understanding the installation helps clarify T3 Code’s architecture: 
┌─────────────────────────────────────────┐
│  Installation Method                     │
├─────────────────────────────────────────┤
│  NPX          │  Desktop App             │
│  - CLI entry  │  - Electron wrapper      │
│  - NPM pkg    │  - Bundled server        │
└───────┬───────┴──────────┬───────────────┘
        │                  │
        v                  v
┌─────────────────────────────────────────┐
│  apps/server (Node.js)                  │
│  - WebSocket server (port 3773)         │
│  - HTTP server (serves React app)       │
│  - ProviderManager                      │
│  - CodexAppServerManager                │
└──────────────┬──────────────────────────┘
               │ JSON-RPC over stdio
┌──────────────▼──────────────────────────┐
│  codex app-server                       │
│  - Requires Codex CLI installed         │
│  - Started per session                  │
└─────────────────────────────────────────┘

​
Verification

Verify your installation is working correctly:
1

Check Codex CLI

codex --version
# Should output version information

which codex
# Should output path to codex binary
2

Check T3 Code

npx t3 --version
# Should output: 0.0.3 (or current version)
3

Test connection

  1. Start T3 Code
  2. Open browser to http://localhost:3773 (NPX) or use the desktop window
  3. Check that WebSocket connects successfully
  4. Create a test session
If you can start a session and interact with Codex, installation is complete!

​
Uninstallation

NPX runs T3 Code without permanent installation. To clear cache:
npm cache clean --force

​
Troubleshooting Installation

T3 Code requires Codex CLI to be installed first:
# Verify Codex is on PATH
which codex

# If not found, install from:
# https://github.com/openai/codex
T3 Code requires Node.js 22.13+, 23.4+, or 24.10+:
node --version

# Use nvm to install the correct version:
nvm install 24
nvm use 24
macOS may block unsigned applications:
  1. Go to System Settings → Privacy & Security
  2. Click Open Anyway next to the T3 Code warning
  3. Or right-click the app and select Open
Another instance of T3 Code is running:
# Find the process
lsof -i:3773

# Kill it
lsof -ti:3773 | xargs kill -9
Ensure you’re using the correct Bun version:
bun --version
# Should be 1.3.9+

# Reinstall dependencies
rm -rf node_modules
bun install

# Try building again
bun run build

​
Next Steps

Quickstart Guide

Get T3 Code running and start your first session

Configuration

Customize server options and environment variables

Runtime Modes

Understand Full Access vs Supervised modes

Development Setup

Set up a development environment for contributing
Need help? Join our Discord community or open an issue on GitHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us