Main Features of t3code: AI Coding Agent GUI Architecture Explained

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 using the makeCodexAdapterLive function. Similarly, the Claude adapter lives in 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, which handles the ServerPushBus and readiness gating. On the client side, 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. 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, 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, which renders the primary chat interface, and 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.

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, while the bridge implementation resides in the Electron main process. Browser-side usage is handled in 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, which exports the runServer function. Observability is implemented via apps/server/src/observability/Layers/Observability.ts, featuring the RuntimeReceiptBusLive for lightweight telemetry.

Practical Code Examples

Starting the Development Server

# 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) and the Vite dev server for the React UI.

Opening a WebSocket Session

// 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).

Adding a New Provider Adapter

// 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). 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

// 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. 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 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 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.

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