How to Clone the t3code Repository: Complete Setup and Architecture Guide

Run git clone https://github.com/pingdotgg/t3code.git to download the repository, then cd t3code and bun install to set up the Effect-TS-based WebSocket coding environment.

The t3code repository is an open-source coding agent platform built by Theo Browne's Ping Labs. When you clone the t3code repository, you get a full-stack TypeScript application featuring a React frontend and Node.js WebSocket server orchestrated through Effect-TS layers.

Step-by-Step: Clone the t3code Repository

Clone the Repository

Open your terminal and run the standard Git clone command pointing at the canonical HTTPS URL:

git clone https://github.com/pingdotgg/t3code.git

This creates a new directory named t3code containing the entire source tree. The repository includes the server runtime in apps/server/src/server.ts, the React web client in apps/web, and shared contract definitions in packages/contracts/src/ws.ts.

Navigate and Verify

Change into the freshly cloned directory and confirm the checkout succeeded:

cd t3code
git status        # should show "On branch main" with no local changes

ls -R | head -n 20   # glance at the top-level files

Install Dependencies

The project uses Bun as its package manager and runtime. Install all dependencies with:

bun install

If you use mise for toolchain management, you can optionally run mise install first to ensure the correct Bun and Node versions are active.

T3code Architecture Overview

T3code operates as a Node.js WebSocket server that wraps an external coding-agent process (the Codex app-server) and serves a React + Vite web UI. The architecture uses Effect-TS for dependency injection and error handling, with each concern isolated in its own layer.

Core Runtime Components

The data flow follows this pattern:

Browser (React + Vite)  ⇄  WebSocket (wsTransport)  ⇄  apps/server (Node.js)
   │                                                    │
   └─►  JSON-RPC ↔ codex app-server (provider runtime) ◄─┘

• Browser side – The UI in apps/web opens a WebSocket connection, receives typed push events, and updates local state via WsTransport and wsNativeApi.
• Server side – apps/server/src/server.ts hosts static assets, handles WebSocket traffic, starts the provider runtime, and emits ordered pushes through a ServerPushBus.
• Provider runtime – Actual coding agents (Codex, Claude, etc.) run in a separate process (codex app-server). Communication occurs over JSON-RPC on stdio.

The authoritative architectural description lives in .docs/architecture.md, and the server startup composition is implemented in apps/server/src/server.ts.

Effect-TS Layer System

The server builds a large Effect-TS layer graph to manage dependencies:

Layer	Responsibility	Key Source
HttpServerLive	HTTP listener (Bun or Node)	apps/server/src/server.ts (lines 92-113)
ProviderLayerLive	Loads provider adapters (Codex, Claude, OpenCode, Cursor) and registers them	apps/server/src/server.ts (lines 46-80)
ReactorLayerLive	Orchestration reactors, ingestion, command handling, checkpointing	apps/server/src/server.ts (lines 28-35)
WorkspaceLayerLive	Handles file-system interactions and Git integration	apps/server/src/server.ts (lines 100-115)
AuthLayerLive	Authentication & secret management	apps/server/src/server.ts (lines 16-19)
RuntimeServicesLive	Merges all runtime dependencies and starts the server	apps/server/src/server.ts (lines 26-45)

These layers are instantiated in makeServerLayer and launched by runServer at the bottom of apps/server/src/server.ts.

Data Flow on a User Turn

1. Browser sends a typed request over the WebSocket via packages/contracts/src/ws.ts definitions.
2. wsServer (the server's WebSocket handler) decodes the request.
3. The request routes to ProviderService, which talks to the provider via JSON-RPC.
4. Provider events are ingested by ProviderRuntimeIngestion, normalized into orchestration events, and persisted by OrchestrationEngine.
5. The server pushes the resulting orchestration.domainEvent back to the browser through ServerPushBus.

Development Workflow

Running the Development Server

After you clone the t3code repository and install dependencies, start the development environment with:

bun run dev

This command launches both the Node-based WebSocket server (listening on the port defined in ServerConfig) and the Vite dev server that serves the React UI with hot-reload enabled.

Production Build Process

To create a production build:

bun run build        # bundles the React app and compiles the server

bun run start        # runs the compiled server in production mode

The build process generates optimized static assets for the web client and a compiled server runtime ready for deployment.

Zero-Install Alternative

If you prefer not to clone the repository at all, the project ships a binary entry point:

npx t3               # fetches the latest packaged version and starts the client

This approach downloads the pre-built client without requiring a local Git clone or dependency installation.

Key Files and Entry Points

Understanding the repository structure helps navigate the codebase after you clone the t3code repository:

File	Role	Direct Link
README.md	High-level project description, installation notes, quick start commands	README.md
.docs/architecture.md	Full architectural diagram, component responsibilities, event lifecycle	architecture.md
apps/server/src/server.ts	Composition of all Effect-TS layers, HTTP & WebSocket setup, server launch	server.ts
apps/web/src/wsTransport.ts	Browser-side WebSocket transport, typed push handling	wsTransport.ts
apps/web/src/nativeApi.ts	Bridge between UI actions and typed WebSocket requests	nativeApi.ts
packages/contracts/src/ws.ts	Shared WebSocket contract definitions (push/event types)	ws.ts
packages/shared/src/DrainableWorker.ts	Queue-backed worker implementation used by reactors	DrainableWorker.ts

These files provide a complete view of how the repository is structured, how the server boots via makeServerLayer in apps/server/src/server.ts, and how the front-end communicates with the back-end through the contracts defined in packages/contracts/src/ws.ts.

Summary

• Clone the t3code repository with git clone https://github.com/pingdotgg/t3code.git to obtain the full Effect-TS coding agent platform.
• Install dependencies using bun install after navigating into the t3code directory.
• Start development with bun run dev to launch both the WebSocket server and React Vite frontend.
• Understand the architecture through key files like apps/server/src/server.ts (layer composition) and .docs/architecture.md (data flow diagrams).
• Deploy production builds using bun run build followed by bun run start.

Frequently Asked Questions

Does the t3code repository require specific system dependencies?

Yes, the t3code repository requires Bun as its primary runtime and package manager. While Node.js is used for certain compatibility layers, the development scripts in package.json assume the bun command is available. Optionally, you can use mise to manage tool versions by running mise install after cloning.

What is the fastest way to run t3code without cloning?

You can use the zero-install binary entry point by running npx t3 in your terminal. This command fetches the latest packaged version from the npm registry and starts the client immediately without requiring a local Git clone or dependency installation. However, for development or customization, you should still clone the t3code repository directly.

How does the server architecture work after cloning?

The server in apps/server/src/server.ts uses Effect-TS to compose a layered architecture. When you run bun run dev, the server boots through makeServerLayer, which wires together HttpServerLive (HTTP listener), ProviderLayerLive (coding agent adapters), ReactorLayerLive (orchestration), and ServerPushBus (event streaming). The browser connects via WebSocket using contracts defined in packages/contracts/src/ws.ts.

Can I use npm or yarn instead of Bun to clone and run t3code?

While the repository might work with other package managers, the official tooling and scripts are optimized for Bun. The package.json scripts use bun commands, and the server runtime in apps/server/src/server.ts is designed to leverage Bun's performance characteristics. For the most reliable setup after you clone the t3code repository, install Bun and use bun install followed by bun run dev.

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