# Main Features of t3code: AI Coding Agent GUI Architecture Explained

> Explore the main features of t3code, a high-performance AI coding agent GUI. Discover its Node.js WebSocket server, React frontend, multi-provider support, Git integration, and Electron bridge.

- Repository: [Ping.gg/t3code](https://github.com/pingdotgg/t3code)
- Tags: architecture
- Published: 2026-04-18

---

**t3code is a minimal, high-performance web GUI for AI coding agents that combines a Node.js WebSocket server with a React frontend, featuring multi-provider support, session persistence, Git integration, and a desktop Electron bridge.**

t3code is an open-source project from **pingdotgg/t3code** that provides a unified interface for AI coding agents like Codex, Claude, and Cursor. Built with **Effect** layers for composability and **WebSocket** orchestration for real-time updates, t3code delivers a desktop-class coding experience through a web-based architecture.

## Multi-Provider AI Agent Support

t3code abstracts multiple AI providers behind a common `ProviderService` interface. Each adapter communicates with its native CLI—such as `codex` or `claude`—via **JSON-RPC over stdio**.

The **Codex adapter** is implemented in [`apps/server/src/provider/Layers/CodexAdapter.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/provider/Layers/CodexAdapter.ts) using the `makeCodexAdapterLive` function. Similarly, the **Claude adapter** lives in [`apps/server/src/provider/Layers/ClaudeAdapter.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/provider/Layers/ClaudeAdapter.ts). Both implement the `ProviderAdapter` contract defined in the contracts package, ensuring that adding support for new agents requires only implementing the adapter interface without touching UI code.

## Deterministic WebSocket Orchestration

At the heart of t3code is a **single ordered push bus** (`ServerPushBus`) that streams typed domain events to the browser. This architecture guarantees deterministic ordering and eliminates race conditions that typically plague real-time coding interfaces.

The WebSocket server implementation resides in [`apps/server/src/wsServer.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/wsServer.ts), which handles the `ServerPushBus` and readiness gating. On the client side, [`apps/web/src/wsTransport.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/wsTransport.ts) contains the `WsTransport` class that decodes pushes and publishes them to the React state machine.

## Session Persistence and Checkpointing

t3code persists sessions in **SQLite**, allowing users to resume long-running coding tasks. The **checkpointing system** generates diffs on demand, ensuring that lengthy turns do not block the UI.

The checkpoint store logic is implemented in [`apps/server/src/checkpointing/Layers/CheckpointStore.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/checkpointing/Layers/CheckpointStore.ts). This layer integrates with the provider service to capture state snapshots at strategic points during agent execution.

## Native Git Integration

The application provides full **Git awareness** directly in the UI, showing changed files, diffs, and allowing commits without leaving the interface. The server watches the repository via `GitCoreLive` and broadcasts changes as orchestration events.

Implementation details are found in [`apps/server/src/git/Layers/GitCore.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/git/Layers/GitCore.ts), which handles repository status monitoring and diff generation.

## Rich React UI Components

The frontend is built with **React and Vite**, featuring a comprehensive component library including a chat view, composer, terminal emulator, diff panel, file-tree, and provider-model picker.

Key components include [`apps/web/src/components/chat/ChatView.tsx`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/components/chat/ChatView.tsx), which renders the primary chat interface, and [`apps/web/src/components/chat/TerminalContextInlineChip.tsx`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/components/chat/TerminalContextInlineChip.tsx) for inline terminal context. The UI uses **Tailwind CSS** for styling and implements a customizable **key-binding system** defined in [`packages/shared/src/keybindings.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/shared/src/keybindings.ts).

## Desktop-Native Bridge via Electron

When running as an **Electron app**, t3code exposes native OS capabilities through a lightweight `desktopBridge`. This allows the UI to invoke folder pickers, context menus, and secret storage securely.

The IPC contract is defined in [`packages/contracts/src/ipc.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ipc.ts), while the bridge implementation resides in the Electron main process. Browser-side usage is handled in [`apps/web/src/localApi.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/localApi.ts).

## Extensible Effect-Layer Architecture

All server functionality is composed using **Effect** layers, making the codebase highly modular and testable. New services—such as additional AI providers or observability tools—can be added by implementing the appropriate layer interface.

The main server composition is in [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts), which exports the `runServer` function. Observability is implemented via [`apps/server/src/observability/Layers/Observability.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/observability/Layers/Observability.ts), featuring the `RuntimeReceiptBusLive` for lightweight telemetry.

## Practical Code Examples

### Starting the Development Server

```bash

# Install dependencies (once)

bun install .

# Web-only hot-reload

bun run dev

# Desktop-enabled hot-reload (starts both web UI and Electron bridge)

bun run dev:desktop

```

The `dev` scripts launch the **WebSocket server** (`runServer` exported from [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts)) and the Vite dev server for the React UI.

### Opening a WebSocket Session

```tsx
// apps/web/src/components/chat/ChatView.tsx (simplified)
const ws = new WebSocket(`ws://localhost:${import.meta.env.VITE_WS_PORT}`);
ws.addEventListener("message", (ev) => {
  const event = JSON.parse(ev.data);
  // All domain events are typed in contracts → ws.ts
});

```

The client receives `orchestration.domainEvent` pushes that drive the UI state machine (`WsTransport` in [`apps/web/src/wsTransport.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/wsTransport.ts)).

### Adding a New Provider Adapter

```ts
// apps/server/src/provider/Layers/MyAIAdapter.ts
export const makeMyAIAdapterLive = (options?: { logger?: Logger }) =>
  Layer.effect(
    ProviderAdapter,
    Effect.gen(function* () {
      const logger = yield* Option.getOrUndefined(options?.logger);
      // Connect to MyAI CLI via stdio JSON-RPC
      const rpc = yield* MyAIClient.make({ logger });
      return ProviderAdapter.of({
        name: "myai",
        send: (msg) => rpc.send(msg),
        shutdown: () => rpc.shutdown(),
      });
    })
  );

```

Register the adapter in `ProviderAdapterRegistryLive` (see [`apps/server/src/provider/Layers/ProviderAdapterRegistry.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/provider/Layers/ProviderAdapterRegistry.ts)). Because the server composes everything with `Effect` layers, the new provider becomes instantly available to the UI without any additional wiring.

### Using the Desktop Bridge

```ts
// apps/web/src/localApi.ts (browser side)
export async function pickFolder(options: { title: string }): Promise<string | null> {
  if (!window.desktopBridge) return null;
  return window.desktopBridge.pickFolder(options);
}

```

The bridge implementation lives in the Electron main process (`desktopBridge` defined in the `ipc` contract) and forwards the request to native OS dialogs.

## Summary

t3code’s main capabilities include:

- **Multi-agent orchestration** supporting Codex, Claude, Open-Code, and Cursor through a unified provider layer.
- **Deterministic WebSocket-driven UI** using a typed push bus for ordered event streaming.
- **Session persistence and checkpointing** with SQLite-backed storage and on-demand diff generation.
- **Native Git integration** providing repository awareness, diff viewing, and commit capabilities.
- **Rich React component library** featuring chat, terminal, and diff views styled with Tailwind.
- **Desktop-native bridge** enabling OS-level dialogs and secure storage via Electron.
- **Extensible Effect-layer architecture** allowing straightforward addition of new AI providers and services.

## Frequently Asked Questions

### What AI providers does t3code support?

t3code currently supports **Codex**, **Claude**, **Open-Code**, and **Cursor** through adapter layers located in `apps/server/src/provider/Layers/`. Each adapter communicates with its respective CLI via JSON-RPC over stdio, allowing the UI to interact with multiple agents through a single consistent interface.

### How does t3code handle real-time updates between the server and UI?

The application uses a **WebSocket orchestration layer** centered around the `ServerPushBus` in [`apps/server/src/wsServer.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/wsServer.ts). This bus streams typed domain events to the browser in a strictly ordered fashion, eliminating race conditions. The client-side `WsTransport` in [`apps/web/src/wsTransport.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/wsTransport.ts) decodes these events and updates the React state machine accordingly.

### Can t3code be extended to support new AI agents?

Yes, the server is built with **Effect layers** that make extension straightforward. To add a new provider, you implement the `ProviderAdapter` interface in a new file under `apps/server/src/provider/Layers/` and register it in `ProviderAdapterRegistryLive`. Because the architecture uses dependency injection via Effect, the new adapter becomes available throughout the application without modifying UI code or WebSocket handlers.

### What is the difference between the web and desktop versions of t3code?

The **web version** runs in a browser and connects to the WebSocket server directly, suitable for development workflows using `bun run dev`. The **desktop version** (built with Electron) includes a `desktopBridge` defined in [`packages/contracts/src/ipc.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ipc.ts) that exposes native OS capabilities like folder pickers, context menus, and secret storage. You can launch the desktop version with `bun run dev:desktop` or run the pre-built binary with `npx t3`.