How to Fork the t3code Repository: A Complete Guide

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:

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 (the core WebSocket server) and 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:

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

Create a Feature Branch

Before making changes, create an isolated branch:

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 (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 (client-side transport).
• packages/contracts – TypeScript-only contracts shared between server and client (no runtime code). Key entry point: 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 that explains the runtime flow, and a quick-start guide in the root 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:

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

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:

# 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	High-level description, install instructions, and quick-start command
.docs/architecture.md	Visual overview of the server-client flow, background workers, and event lifecycle
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	Browser-side transport handling typed WebSocket messages
packages/contracts/src/ws.ts	Shared TypeScript contracts that guarantee type-safe communication between server and client
apps/server/src/provider/Layers/ProviderService.ts	Orchestrates provider sessions (Codex / Claude) and communicates via JSON-RPC
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 and 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.

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