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

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.
• apps/web – React UI that consumes server pushes and sends user actions back. Key entry point: 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.

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

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:

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:

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:

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

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 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. This file initializes the WebSocket server, starts the provider runtime via 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 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 for type additions or 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 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. 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.

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