T3 Code

T3 Code is a minimal web GUI for coding agents. Currently Codex-first, with Claude Code support coming soon.

Run npx t3 in any project directory to launch the web interface. Run bun run dev:desktop to launch the Electron desktop app in this monorepo.

Architecture

T3 Code runs as a Node.js WebSocket server that wraps codex app-server (JSON-RPC over stdio) and serves a React web app.

┌─────────────────────────────────┐
│  Browser (React + Vite)         │
│  Connected via WebSocket        │
└──────────┬──────────────────────┘
           │ ws://localhost:3773
┌──────────▼──────────────────────┐
│  apps/server (Node.js)          │
│  WebSocket + HTTP static server │
│  ProviderManager                │
│  CodexAppServerManager          │
└──────────┬──────────────────────┘
           │ JSON-RPC over stdio
┌──────────▼──────────────────────┐
│  codex app-server               │
└─────────────────────────────────┘

Workspace layout

• /apps/server: Node.js WebSocket server. Wraps Codex app-server, serves the built web app, and opens the browser on start.
• /apps/web: React + Vite UI. Session control, conversation, and provider event rendering. Connects to the server via WebSocket.
• /apps/desktop: Electron shell. Spawns a desktop-scoped t3 backend process and loads the shared web app.
• /packages/contracts: Shared Zod schemas and TypeScript contracts for provider events, WebSocket protocol, and model/session types.

Codex prerequisites

• Install Codex CLI so codex is on your PATH.
• Authenticate Codex before running T3 Code (for example via API key or ChatGPT auth supported by Codex).
• T3 Code starts the server via codex app-server per session.

Quick start

# Development (with hot reload)
bun run dev

# Desktop development
bun run dev:desktop

# Desktop development on an isolated port set
T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop

# Production
bun run build
bun run start

# Build a shareable macOS .dmg (arm64 by default)
bun run dist:desktop:dmg

# Or from any project directory after publishing:
npx t3

Scripts

• bun run dev — Starts contracts, server, and web in turbo watch mode.
• bun run dev:server — Starts just the WebSocket server (uses Bun TypeScript execution).
• bun run dev:web — Starts just the Vite dev server for the web app.
• Dev commands default T3CODE_STATE_DIR to ~/.t3/dev to keep dev state isolated from desktop/prod state.
• Override server CLI-equivalent flags from root dev commands with --, for example: bun run dev -- --state-dir ~/.t3/another-dev-state
• bun run start — Runs the production server (serves built web app as static files).
• bun run build — Builds contracts, web app, and server through Turbo.
• bun run typecheck — Strict TypeScript checks for all packages.
• bun run test — Runs workspace tests.
• bun run dist:desktop:artifact -- --platform <mac|linux|win> --target <target> --arch <arch> — Builds a desktop artifact for a specific platform/target/arch.
• bun run dist:desktop:dmg — Builds a shareable macOS .dmg into ./release.
• bun run dist:desktop:dmg:x64 — Builds an Intel macOS .dmg.
• bun run dist:desktop:linux — Builds a Linux AppImage into ./release.
• bun run dist:desktop:win — Builds a Windows NSIS installer into ./release.

Desktop .dmg packaging notes

• Default build is unsigned/not notarized for local sharing.
• The DMG build uses assets/macos-icon-1024.png as the production app icon source.
• Desktop production windows load the bundled UI from t3://app/index.html (not a 127.0.0.1 document URL).
• Desktop packaging includes apps/server/dist (the t3 backend) and starts it on loopback with an auth token for WebSocket/API traffic.
• Your tester can still open it on macOS by right-clicking the app and choosing Open on first launch.
• To keep staging files for debugging package contents, run: bun run dist:desktop:dmg -- --keep-stage
• To allow code-signing/notarization when configured in CI/secrets, add: --signed.
• Windows --signed uses Azure Trusted Signing and expects: AZURE_TRUSTED_SIGNING_ENDPOINT, AZURE_TRUSTED_SIGNING_ACCOUNT_NAME, AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME, and AZURE_TRUSTED_SIGNING_PUBLISHER_NAME.
• Azure authentication env vars are also required (for example service principal with secret): AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET.

Running multiple dev instances

Set T3CODE_DEV_INSTANCE to any value to deterministically shift all dev ports together.

• Default ports: server 3773, web 5733
• Shifted ports: base + offset (offset is hashed from T3CODE_DEV_INSTANCE)
• Example: T3CODE_DEV_INSTANCE=branch-a bun run dev:desktop

If you want full control instead of hashing, set T3CODE_PORT_OFFSET to a numeric offset.

Runtime modes

T3 Code has a global runtime mode switch in the chat toolbar:

• Full access (default): starts sessions with approvalPolicy: never and sandboxMode: danger-full-access.
• Supervised: starts sessions with approvalPolicy: on-request and sandboxMode: workspace-write, then prompts in-app for command/file approvals.

Provider architecture

The web app communicates with the server via WebSocket using a simple JSON-RPC-style protocol:

• Request/Response: { id, method, params } → { id, result } or { id, error }
• Push events: { type: "push", channel, data } for orchestration read-model updates

Methods mirror the NativeApi interface defined in @t3tools/contracts:

• providers.startSession, providers.sendTurn, providers.interruptTurn
• providers.respondToRequest, providers.stopSession
• shell.openInEditor, server.getConfig

Codex is the only implemented provider. claudeCode is reserved in contracts/UI.

CI quality gates

• .github/workflows/ci.yml runs bun run lint, bun run typecheck, and bun run test on pull requests and pushes to main.
• .github/workflows/release.yml builds macOS (arm64 and x64), Linux (x64), and Windows (x64) desktop artifacts from a single v*.*.* tag and publishes one GitHub release.
• The release workflow auto-enables signing only when secrets are present: Apple credentials for macOS and Azure Trusted Signing credentials for Windows. Without secrets, it still releases unsigned artifacts.
• See docs/release.md for full release/signing setup checklist.