# How to Contribute Code to t3code: A Step-by-Step Guide for Open Source Developers

> Learn how to contribute code to pingdotgg/t3code. Follow our step-by-step guide for forking, setting up, and submitting your first pull request to this open-source project.

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

---

**To contribute code to t3code, fork the repository, install dependencies with Bun, create a focused branch under 200 lines of changes, run `bun fmt && bun lint && bun typecheck`, and submit a PR that targets small bug fixes or reliability improvements.**

The t3code repository (`pingdotgg/t3code`) is an early-stage Node.js WebSocket server that wraps the Codex/Claude app-server using JSON-RPC over stdio. If you want to contribute code to t3code, you must understand its strict contribution policy: only small, focused bug fixes, reliability tweaks, and maintenance work that does not change the project's direction are likely to be merged.

## Understanding the t3code Architecture

Before you contribute code to t3code, familiarize yourself with its monorepo structure. The system coordinates between a WebSocket server, a React frontend, and shared TypeScript contracts.

### Core Packages and Entry Points

The repository organizes functionality into three main packages:

- **`apps/server`** – Coordinates the WebSocket server and streams typed push events to the browser. Key entry point: [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts).
- **`apps/web`** – React UI that consumes server pushes and sends user actions back. Key entry point: [`apps/web/src/wsTransport.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/wsTransport.ts).
- **`packages/contracts`** – Shared TypeScript contracts (schemas, WebSocket messages, provider events) used by both server and client. Key file: [`packages/contracts/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ws.ts).

### Provider Runtime and Event Flow

The provider runtime (Codex app-server) spawns as a child process and communicates via JSON-RPC, as implemented in [`apps/server/src/provider/codexAppServer.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/provider/codexAppServer.ts). All runtime events normalize into orchestration domain events and push through a single ordered bus (`ServerPushBus`) to the UI. Background workers in [`packages/shared/src/DrainableWorker.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/shared/src/DrainableWorker.ts) handle async work like checkpointing, ensuring deterministic test behavior.

## Preparing Your Development Environment

To successfully contribute code to t3code, you need Bun installed and the repository forked locally.

### Forking and Cloning the Repository

Start by creating your own copy of the repository:

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

```

Replace `<your-username>` with your GitHub handle. This creates a personal workspace where you can experiment without affecting the main codebase.

### Installing Dependencies with Bun

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

```bash
bun install

```

If you use `mise` for version management, you can also run `mise install` to ensure the correct runtime versions. Verify your setup by checking that `bun --version` reports a compatible version (the project typically tracks the latest stable Bun release).

## Contribution Workflow for t3code

The maintainers enforce a strict workflow to ensure code quality and project focus. Follow these steps exactly to maximize the chance of your contribution being accepted.

### Creating Focused Feature Branches

Create a descriptive branch for your work:

```bash
git checkout -b fix/short-description

```

Keep your changes under **200 lines** of code. Large PRs are automatically flagged as `size:large` and are almost always closed. The project only accepts small, focused bug fixes, reliability improvements, or performance tweaks that do not alter the project's direction.

### Code Quality and CI Checks

Before committing, run the mandatory formatting and linting commands:

```bash
bun fmt
bun lint
bun typecheck

```

These commands enforce the project's code style and catch type errors. The CI pipeline (defined in [`.github/workflows/ci.yml`](https://github.com/pingdotgg/t3code/blob/main/.github/workflows/ci.yml)) runs these same checks, and PRs will be blocked if they fail. Commit messages should use the imperative mood (e.g., `"fix: correct spelling typo in README"`).

### Testing Your Changes

Run the full test suite to ensure no regressions:

```bash
bun run test

```

The project uses deterministic testing facilitated by the `DrainableWorker` queue system. If you've modified the WebSocket transport or provider runtime, verify that both server-side and client-side contracts remain synchronized by checking [`packages/contracts/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ws.ts) for any type changes that need propagation.

## Key Files and Code Patterns

When you contribute code to t3code, you'll likely interact with these specific files and patterns.

### Server-Side Entry Points

The main server bootstrap resides in [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts). This file initializes the WebSocket server, starts the provider runtime via [`apps/server/src/codexAppServerManager.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/codexAppServerManager.ts), and serves static assets. If you're fixing server-side reliability issues, check the `ServerPushBus` implementation for event streaming logic.

### Shared Contracts and Type Safety

The `packages/contracts` directory is the safest place to make small additions, as both `apps/server` and `apps/web` depend on it. The file [`packages/contracts/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ws.ts) defines the typed WebSocket messages that ensure type safety across the full stack. When modifying contracts, ensure you update both the server and client implementations to maintain synchronization.

## Summary

To successfully contribute code to t3code, remember these essential points:

- **Fork and clone** the `pingdotgg/t3code` repository, then install dependencies with `bun install`.
- **Keep changes small** – under 200 lines – and focused on bug fixes, reliability, or performance improvements.
- **Run quality checks** with `bun fmt`, `bun lint`, and `bun typecheck` before submitting.
- **Test thoroughly** using `bun run test` to ensure deterministic behavior.
- **Focus on safe files** like [`packages/contracts/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ws.ts) for type additions or [`apps/server/src/server.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/server.ts) for server logic.

## Frequently Asked Questions

### What types of contributions does t3code accept?

The t3code project only accepts **small, focused bug fixes**, **reliability improvements**, and **performance tweaks** that do not change the project's direction. Large feature additions or architectural changes are almost always rejected. The maintainer team intentionally keeps the scope narrow to maintain the project's focus as a Node.js WebSocket wrapper for the Codex/Claude app-server.

### Why was my pull request labeled "vouch:unvouched"?

Pull requests from contributors not listed in `.github/VOUCHED.td` automatically receive the `vouch:unvouched` label. This is a security measure for the early-stage project. After you submit a successful, merged contribution, a maintainer may add you to the trust list, which removes the unvouched status from future PRs. The label works alongside automatic size labels (`size:xs`, `size:large`, etc.) to categorize submissions.

### How do I ensure my code passes the CI pipeline?

The CI pipeline in [`.github/workflows/ci.yml`](https://github.com/pingdotgg/t3code/blob/main/.github/workflows/ci.yml) runs three mandatory checks: `bun fmt` for formatting, `bun lint` for linting, and `bun typecheck` for TypeScript validation. You must also ensure `bun run test` passes locally before pushing. Run these commands in order after making changes but before committing. If any check fails, the pull request will be blocked from merging until you fix the issues and push an update.

### What is the best file to modify for WebSocket message changes?

If you need to modify WebSocket message types or add new event contracts, edit [`packages/contracts/src/ws.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/ws.ts). This file contains the shared TypeScript definitions used by both the server (`apps/server`) and the web client (`apps/web`). Because both sides depend on this package, it is the safest place for small type additions that maintain type safety across the full stack. Always verify that changes here compile in both the server and client packages before submitting.