Installation

Complete installation guide for T3 Code - NPM, desktop app, and prerequisites

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

NPX Method

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.

Desktop App

No additional runtime required

The desktop app bundles everything needed, including:

• Electron runtime
• Node.js environment
• All dependencies

You only need Codex CLI installed separately.

Installation Methods

NPX (Recommended for quick start)

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:

   macOS

   Download: .dmg file

   Available 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
   

   Windows

   Download: .exe installer (NSIS)

   Architecture:

   • x64 (64-bit Windows)

   Build from source

   bun run dist:desktop:win
   

   Linux

   Download: .AppImage

   Architecture:

   • x64 (64-bit Linux)

   Build from source

   bun run dist:desktop:linux
   

   Make the AppImage executable:

   chmod +x T3Code-*.AppImage
   ./T3Code-*.AppImage
   
2. Install the application

   macOS

   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

   Windows

   1. Run the downloaded .exe installer
   2. Follow the installation wizard
   3. Launch from the Start Menu or desktop shortcut

   Linux

   No installation required for AppImage:

   chmod +x T3Code-*.AppImage
   ./T3Code-*.AppImage
   

   Optional: Integrate with system menu using AppImageLauncher

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

   Web Development

   Run with hot reload:

   bun run dev
   

   This starts:

   • Server at localhost:3773
   • Web client with Vite HMR

   Desktop Development

   Run the Electron app in development mode:

   bun run dev:desktop
   

   For isolated testing (different port set):

   T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop
   
4. Build for production

   Server & Web

   bun run build
   bun run start
   

   # Build all desktop artifacts
   bun run dist:desktop:artifact
   
   # Or specific platform:
   bun run dist:desktop:dmg      # macOS DMG
   bun run dist:desktop:win      # Windows installer
   bun run dist:desktop:linux    # Linux AppImage
   

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

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

   Desktop

   Open the app and check Help → About (macOS) or Help → About (Windows/Linux)

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

NPX runs T3 Code without permanent installation. To clear cache:

npm cache clean --force

Desktop App

macOS

1. Move T3 Code.app from Applications to Trash
2. Remove application support files (optional):
   rm -rf ~/Library/Application\ Support/T3Code
   rm -rf ~/Library/Caches/T3Code
   

Windows

1. Uninstall via Settings → Apps → T3 Code → Uninstall
2. Or run the uninstaller from the installation directory

Linux

Simply delete the AppImage file:

rm T3Code-*.AppImage

Troubleshooting Installation

Codex CLI not found during 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

Node version mismatch (NPX)

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

Desktop app won't launch (macOS)

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

Port 3773 already in use

Another instance of T3 Code is running:

# Find the process
lsof -i:3773

# Kill it
lsof -ti:3773 | xargs kill -9

Build failed (development)

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.