# How to Fork the t3code Repository: A Complete Guide

> Learn how to fork the t3code repository with this comprehensive guide. Follow simple steps to clone, set up upstream, and start developing your features.

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

---

**To fork the t3code repository, click the Fork button on the GitHub repository page, clone your copy to your local machine, add the original repository as an upstream remote, and create a feature branch to begin development.**

Forking the **t3code** repository from `pingdotgg/t3code` creates an independent copy of the entire monorepo under your GitHub account, allowing you to experiment with the WebSocket server, React client, and shared contracts without affecting the original codebase. This guide walks you through the complete process to fork the t3code repository, configure your local environment, and understand the key files you'll be working with.

## Step-by-Step Guide to Fork the t3code Repository

### Create Your Fork on GitHub

Navigate to the repository at `https://github.com/pingdotgg/t3code` and click the **Fork** button in the top-right corner. GitHub will copy the repository into `your-username/t3code`, preserving the full monorepo structure including `apps/server`, `apps/web`, and `packages/contracts`.

### Clone Your Fork Locally

Replace `<your-username>` with your GitHub handle and run:

```bash
git clone https://github.com/<your-username>/t3code.git
cd t3code

```

This downloads the entire codebase, including critical files like [`apps/server/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/ws.ts) (the core WebSocket server) and [`apps/web/src/rpc/wsTransport.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/rpc/wsTransport.ts) (the client-side transport).

### Configure the Upstream Remote

Keep a reference to the original repository so you can pull updates later:

```bash
git remote add upstream https://github.com/pingdotgg/t3code.git
git fetch upstream

```

### Create a Feature Branch

Before making changes, create an isolated branch:

```bash
git checkout -b my-experiment

```

## Understanding the t3code Repository Structure

The t3code monorepo contains three primary packages that you will interact with after you fork the t3code repository:

- **apps/server** – Node.js WebSocket server that wraps the Codex app-server and serves the React UI. Key entry point: [`apps/server/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/ws.ts) (core WebSocket layer).
- **apps/web** – Vite-powered React client that renders sessions and talks to the server over WebSocket. Key entry point: [`apps/web/src/rpc/wsTransport.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/rpc/wsTransport.ts) (client-side transport).
- **packages/contracts** – TypeScript-only contracts shared between server and client (no runtime code). Key entry point: [`packages/contracts/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ws.ts) (WebSocket contract definitions).

The repository also contains extensive documentation in the `.docs` folder, including the architecture diagram at [`.docs/architecture.md`](https://github.com/pingdotgg/t3code/blob/main/.docs/architecture.md) that explains the runtime flow, and a quick-start guide in the root [`README.md`](https://github.com/pingdotgg/t3code/blob/main/README.md).

## Working with Your Fork: Common Git Workflows

Once you fork the t3code repository, use these commands to sync your work and manage branches:

```bash

# 1️⃣ Clone your fork

git clone https://github.com/<your-username>/t3code.git
cd t3code

# 2️⃣ Keep the original repo as upstream

git remote add upstream https://github.com/pingdotgg/t3code.git
git fetch upstream

# 3️⃣ Sync your fork with upstream (before starting new work)

git checkout main
git merge upstream/main   # fast-forward to the latest upstream changes

# 4️⃣ Create a branch for a new experiment

git checkout -b feature/awesome-thing

# 5️⃣ After editing files, commit & push

git add .
git commit -m "Add awesome thing"
git push origin feature/awesome-thing

```

### Syncing Your Fork with Upstream

Regularly sync your local `main` branch with the original repository to avoid merge conflicts:

```bash
git checkout main
git fetch upstream
git merge upstream/main
git push origin main

```

### Installing Dependencies

The project uses **bun** for package management. After you fork the t3code repository and clone it locally:

```bash

# Install bun if you don't have it

curl -fsSL https://bun.sh/install | bash

# Install dependencies

bun install .

# Start the development server (web UI + server)

npx t3   # same as `bun run dev` (see package.json scripts)

```

Alternatively, you can use `npm` or `pnpm` if you prefer (`npm i .`).

## Key Files to Explore After Forking

After you fork the t3code repository, explore these critical files to understand the architecture:

| File | Why it matters |
|------|----------------|
| [`README.md`](https://github.com/pingdotgg/t3code/blob/main/README.md) | High-level description, install instructions, and quick-start command |
| [`.docs/architecture.md`](https://github.com/pingdotgg/t3code/blob/main/.docs/architecture.md) | Visual overview of the server-client flow, background workers, and event lifecycle |
| [`apps/server/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/ws.ts) | Core WebSocket server implementation that mediates between the browser and the Codex app-server |
| [`apps/web/src/rpc/wsTransport.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/rpc/wsTransport.ts) | Browser-side transport handling typed WebSocket messages |
| [`packages/contracts/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ws.ts) | Shared TypeScript contracts that guarantee type-safe communication between server and client |
| [`apps/server/src/provider/Layers/ProviderService.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/provider/Layers/ProviderService.ts) | Orchestrates provider sessions (Codex / Claude) and communicates via JSON-RPC |
| [`apps/web/src/lib/chatThreadActions.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/lib/chatThreadActions.ts) | UI actions that trigger server requests (e.g., sending a user turn) |

These files provide a solid foothold in both the client-side UI and the server-side orchestration layers, making it easier to experiment or extend the project after you've forked it.

## Summary

- **Fork the t3code repository** by clicking the Fork button on GitHub to create `your-username/t3code`.
- **Clone locally** using `git clone`, then add the upstream remote to sync with `pingdotgg/t3code`.
- **Understand the monorepo structure**: `apps/server` (WebSocket server), `apps/web` (React client), and `packages/contracts` (shared types).
- **Install dependencies** with `bun install .` and start development with `npx t3`.
- **Explore key files** like [`apps/server/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/ws.ts) and [`apps/web/src/rpc/wsTransport.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/rpc/wsTransport.ts) to understand the WebSocket architecture.

## Frequently Asked Questions

### What's the difference between forking and cloning the t3code repository?

**Forking** creates a copy of the repository under your own GitHub account, allowing you to push changes and open pull requests to the original project. **Cloning** simply downloads the code to your local machine without creating a GitHub-side copy. To contribute to t3code, you must fork first, then clone your fork locally.

### Do I need special permissions to fork t3code?

No, forking is a standard GitHub feature available to anyone with a GitHub account. The t3code repository is public, so you can click the Fork button immediately without requesting access from the maintainers at pingdotgg.

### How do I keep my fork of t3code up to date?

Add the original repository as an upstream remote using `git remote add upstream https://github.com/pingdotgg/t3code.git`, then periodically run `git fetch upstream` followed by `git merge upstream/main` on your local main branch. Push the updated branch to your fork with `git push origin main` to keep GitHub in sync.

### What package manager should I use with t3code?

The project primarily uses **bun** for dependency management and running scripts. After cloning your fork, run `bun install .` to install dependencies and `npx t3` (or `bun run dev`) to start the development server. However, standard npm or pnpm commands also work if you prefer those tools.