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

> Clone the t3code repository with a simple git command. Set up the Effect-TS WebSocket coding environment quickly using bun install. Start building your project now.

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

---

**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:

```bash
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`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts), the React web client in `apps/web`, and shared contract definitions in [`packages/contracts/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ws.ts).

### Navigate and Verify

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

```bash
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:

```bash
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`](https://github.com/pingdotgg/t3code/blob/main/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`](https://github.com/pingdotgg/t3code/blob/main/.docs/architecture.md), and the server startup composition is implemented in [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/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`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts) (lines 92-113) |
| `ProviderLayerLive` | Loads provider adapters (Codex, Claude, OpenCode, Cursor) and registers them | [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts) (lines 46-80) |
| `ReactorLayerLive` | Orchestration reactors, ingestion, command handling, checkpointing | [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts) (lines 28-35) |
| `WorkspaceLayerLive` | Handles file-system interactions and Git integration | [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts) (lines 100-115) |
| `AuthLayerLive` | Authentication & secret management | [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts) (lines 16-19) |
| `RuntimeServicesLive` | Merges all runtime dependencies and starts the server | [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/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`](https://github.com/pingdotgg/t3code/blob/main/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`](https://github.com/pingdotgg/t3code/blob/main/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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/pingdotgg/t3code/blob/main/README.md) | High-level project description, installation notes, quick start commands | [README.md](https://github.com/pingdotgg/t3code/blob/main/README.md) |
| [`.docs/architecture.md`](https://github.com/pingdotgg/t3code/blob/main/.docs/architecture.md) | Full architectural diagram, component responsibilities, event lifecycle | [architecture.md](https://github.com/pingdotgg/t3code/blob/main/.docs/architecture.md) |
| [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts) | Composition of all Effect-TS layers, HTTP & WebSocket setup, server launch | [server.ts](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts) |
| [`apps/web/src/wsTransport.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/wsTransport.ts) | Browser-side WebSocket transport, typed push handling | [wsTransport.ts](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/wsTransport.ts) |
| [`apps/web/src/nativeApi.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/nativeApi.ts) | Bridge between UI actions and typed WebSocket requests | [nativeApi.ts](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/nativeApi.ts) |
| [`packages/contracts/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ws.ts) | Shared WebSocket contract definitions (push/event types) | [ws.ts](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ws.ts) |
| [`packages/shared/src/DrainableWorker.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/shared/src/DrainableWorker.ts) | Queue-backed worker implementation used by reactors | [DrainableWorker.ts](https://github.com/pingdotgg/t3code/blob/main/packages/shared/src/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`](https://github.com/pingdotgg/t3code/blob/main/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`](https://github.com/pingdotgg/t3code/blob/main/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`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts) (layer composition) and [`.docs/architecture.md`](https://github.com/pingdotgg/t3code/blob/main/.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`](https://github.com/pingdotgg/t3code/blob/main/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`](https://github.com/pingdotgg/t3code/blob/main/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`](https://github.com/pingdotgg/t3code/blob/main/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`](https://github.com/pingdotgg/t3code/blob/main/package.json) scripts use `bun` commands, and the server runtime in [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/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`.