How to Run the T3 Code Project: Local Development and Production Deployment

Run bun run dev to start the development server with hot-reload, or execute npx t3 to run the pre-built CLI from any directory without cloning the repository.

T3 Code is a minimal web-based GUI that wraps a Codex or Claude provider inside a Node.js WebSocket server, serving a React and Vite client. If you want to run the T3 Code project locally or deploy it to production, this guide covers the complete setup process from installation to runtime configuration.

Understanding the T3 Code Architecture

Before running the project, it helps to understand the three-layer runtime stack defined in .docs/architecture.md.

The Three-Layer Runtime Stack

1. Provider runtime: A codex app-server process that executes coding agents via JSON-RPC over stdio.
2. Server layer: The Node.js process in apps/server that starts the provider, persists state, and exposes a typed WebSocket API. The entry point is apps/server/src/server.ts.
3. Browser client: A Vite-powered React app in apps/web that connects via typed WebSocket transport (WsTransport). The client router is defined in apps/web/src/router.ts.

Data Flow and Component Interaction

The data flow follows this path: Browser (React) → WebSocket (typed pushes) → Server (OrchestrationEngine) → Provider (codex app-server). When the server boots, it composes Effect-Layer modules for persistence, Git integration, authentication, and analytics, then launches the HTTP and WebSocket stack via makeServerLayer.

Prerequisites and Installation

Installing Bun and Optional Tooling

T3 Code uses Bun as the runtime manager. You can install Bun via the official installer. If you use mise for tool versioning, run mise install first to ensure consistent environment setup.

Project Dependencies Setup

Clone the repository and install dependencies:

bun install .

This command fetches all dependencies for the server, web client, and shared packages.

Running T3 Code in Development Mode

Starting the Dev Server

To run T3 Code in development with hot-reload, execute:

bun run dev

This starts the Node server and Vite dev server concurrently. By default, the web interface is available at http://localhost:3000 and the WebSocket server listens on port 3773.

Desktop Development Mode

For desktop development (Electron-style), run:

bun run dev:desktop

This launches the bundled desktop runtime alongside the development servers. To isolate instances for feature branches, set the T3CODE_DEV_INSTANCE environment variable:

T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop

Building and Running for Production

Production Build Process

To build the T3 Code project for production:

bun run build

This compiles the client using vite build and prepares the server assets. Then start the production server:

bun run start

The server runs in production mode, serving the built client and handling WebSocket connections.

Desktop Distribution

To package the desktop application as a macOS DMG:

bun run dist:desktop:dmg

This uses electron-builder under the hood to create a signed .dmg file for arm64 architecture, outputting to ./dist/t3-code-*.dmg.

Running the Pre-built CLI

After publishing, you can run T3 Code from any directory without cloning the repository:

npx t3

This downloads the latest binary, starts the server, and opens the web UI in your default browser.

Key Configuration and Runtime Components

When running the project, several key components initialize:

• ServerConfig – Located in apps/server/src/config.ts, reads environment variables and CLI flags.
• websocketRpcRouteLayer – Defined in apps/server/src/ws.ts, registers the typed RPC endpoint.
• ProviderAdapterRegistryLive – In apps/server/src/provider/Layers/ProviderAdapterRegistry.ts, wires adapters for Codex, Claude, OpenCode, and Cursor.
• OrchestrationEngine – Found in apps/server/src/orchestration/Layers/OrchestrationEngine.ts, handles event persistence and emits domain events for the UI.

All communication follows the typed WebSocket contracts defined in packages/contracts/src/ws.ts.

Summary

• T3 Code combines a Codex/Claude provider, Node.js WebSocket server, and React/Vite client into a minimal coding GUI.
• Run locally with bun run dev for hot-reload development or bun run dev:desktop for the desktop version.
• Deploy to production using bun run build followed by bun run start, or distribute desktop builds via bun run dist:desktop:dmg.
• Use the CLI anywhere with npx t3 without installing the repository.
• Key files to understand: apps/server/src/server.ts, apps/web/src/router.ts, and packages/contracts/src/ws.ts.

Frequently Asked Questions

How do I install dependencies for the T3 Code project?

Run bun install . in the repository root to fetch all dependencies for the server, web client, and shared packages. If you use mise for tool versioning, run mise install first to ensure Bun and other tools are available.

What ports does T3 Code use in development?

By default, the Vite dev server runs on port 3000 for the web interface, while the WebSocket server listens on port 3773 for client-server communication. You can configure these via environment variables in apps/server/src/config.ts.

Can I run T3 Code without cloning the repository?

Yes. After the package is published, you can execute npx t3 from any directory. This command downloads the latest binary, starts the server, and automatically opens the web UI in your default browser without requiring local source code.

How do I build the desktop version for macOS?

Run bun run dist:desktop:dmg to package the application as a signed .dmg file for arm64 architecture. This uses electron-builder under the hood and outputs the installer to ./dist/t3-code-*.dmg. For development testing, use bun run dev:desktop instead.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}