# How to Report a Bug in t3code: A Complete Guide for Contributors

> Learn how to report a bug in t3code by creating a detailed GitHub issue. Follow our guide for reproduction steps, environment details, and diagnostic logs to help fix issues faster.

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

---

**To report a bug in t3code, create a GitHub issue with a clear title, step-by-step reproduction instructions, environment details (OS, Node/Bun version, and provider version), and diagnostic logs from the server and WebSocket layers; enable tracing using the observability guide in [`docs/observability.md`](https://github.com/pingdotgg/t3code/blob/main/docs/observability.md) to capture the most useful debug data.**

t3code is an open-source AI coding assistant that coordinates LLM providers through a multi-layered architecture. Knowing how to report a bug in t3code effectively requires understanding how the server, web UI, and shared runtime interact, and providing the specific diagnostic data maintainers need to triage issues quickly.

## Understanding t3code Architecture Before Reporting Bugs

Before filing a bug report, identify which of the three logical layers is failing. The repository is organized across distinct domains with clear separation of concerns.

### Server Layer (Node / WebSocket)

The server runs the Codex/Claude app-servers, coordinates provider sessions, and streams domain events to the UI. Key files include:

- [`apps/server/src/codexAppServerManager.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/codexAppServerManager.ts) – starts a provider-specific *app-server* process and wires its JSON-RPC streams.
- [`apps/server/src/providerManager.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/providerManager.ts) – tracks the lifecycle of provider sessions, logs, and error handling.

### Web UI Layer (React + Vite)

The web interface renders the chat view, shows orchestration events, and lets users start or stop sessions. Critical paths include:

- [`apps/web/src/main.tsx`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/main.tsx) – entry point that connects to the WebSocket server.
- [`apps/web/src/components/ChatView.tsx`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/components/ChatView.tsx) – consumes the `orchestration.domainEvent` channel and displays provider output.

### Shared Runtime Utilities

Pure TypeScript helpers used by both server and UI include logging, typed IPC, and Zod schemas:

- [`packages/shared/src/effect.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/shared/src/effect.ts) – lightweight effect helpers (`logDebug`, `logError`) used throughout the codebase.
- [`packages/contracts/src/index.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/index.ts) – schema-only contracts that define the shape of WebSocket messages.

### Common Bug Locations

Because the system is highly asynchronous (processes, streams, and WebSockets), bugs often surface in one of three layers:

1. **Provider-process failures** – the Codex or Claude binary exits or returns malformed JSON.
2. **WebSocket routing / domain-event handling** – messages are dropped, duplicated, or mis-typed.
3. **UI rendering** – the chat view does not update, or state becomes inconsistent after reconnection.

## Essential Information to Include in Your t3code Bug Report

A high-quality bug report for t3code should contain specific diagnostic data that maps to the architecture above.

- **Title** – A short, one-sentence summary, e.g., `Server crashes when Codex returns malformed JSON on Windows`.
- **Description** – What you expected to happen versus what actually happened.
- **Steps to reproduce** – Numbered list that can be followed by anyone:
  1. Install the required provider (`codex login` or `claude auth login`).
  2. Run `npx t3` (or launch the desktop app).
  3. Open a new session, type your prompt, and observe the crash.
- **Environment** – OS, Node/Bun version, provider version, and t3code version (`git rev-parse HEAD`).
- **Logs and diagnostics** – Attach:
  - The console output of the server (`bun run dev` or the desktop log file).
  - Any trace or metric files described in the observability guide (see [`docs/observability.md`](https://github.com/pingdotgg/t3code/blob/main/docs/observability.md)).
- **Screenshots or videos** – UI glitches are easier to understand with visual evidence.

## Step-by-Step Workflow for Reporting a Bug in t3code

Follow this exact workflow to ensure your report reaches the maintainers with full context.

1. **Create a GitHub issue**
   - Go to the repository’s Issues page: `https://github.com/pingdotgg/t3code/issues`.
   - Click **New issue** → **Bug report** (if a template exists; otherwise select *Open a blank issue*).

2. **Fill in the template**
   - Use the sections outlined above: Title, Description, Steps to reproduce, Environment, Logs, and Screenshots.

3. **Label the issue** (if you have permission)
   - Add `bug`, `needs-info`, or `high-priority` as appropriate. The repository automatically adds `vouch:*` and `size:*` labels; you do not need to manage those.

4. **Submit**
   - Click **Submit new issue**.

5. **Follow up**
   - The maintainers may ask for additional logs or a minimal reproduction repository. Be ready to provide a link to a small project that reproduces the bug, or a PR that contains a test case.

## Key Source Files to Reference When Debugging

When investigating or describing a bug, reference these specific files to demonstrate exactly where the failure occurs.

| Area | File | Why it matters for bug reports |
|------|------|-------------------------------|
| Server startup | [`apps/server/src/codexAppServerManager.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/codexAppServerManager.ts) | Starts provider processes; crashes here appear as *provider died*. |
| Provider lifecycle | [`apps/server/src/providerManager.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/providerManager.ts) | Handles session state, logging, and error propagation. |
| WebSocket routing | [`apps/server/src/wsServer.ts`](https://github.com/pingdotgg/t3code/blob/main/apps/server/src/wsServer.ts) | Translates internal events to client-side channels (`orchestration.domainEvent`). |
| UI entry point | [`apps/web/src/main.tsx`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/main.tsx) | Connects to the server; socket errors surface here. |
| Chat view component | [`apps/web/src/components/ChatView.tsx`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/components/ChatView.tsx) | Renders provider output; UI glitches are often traced here. |
| Shared effect helpers | [`packages/shared/src/effect.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/shared/src/effect.ts) | Central place for `logDebug`, `logError`; include these logs in your report. |
| Contracts (type-safe protocol) | [`packages/contracts/src/index.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/contracts/src/index.ts) | Defines message shapes; validation errors point to contract mismatches. |
| Observability guide | [`docs/observability.md`](https://github.com/pingdotgg/t3code/blob/main/docs/observability.md) | Shows how to enable tracing/metrics for server-side bugs. |
| Contributing instructions | [`CONTRIBUTING.md`](https://github.com/pingdotgg/t3code/blob/main/CONTRIBUTING.md) | Explains the project’s stance on contributions and issue etiquette. |

When possible, include code snippets from these files to illustrate exactly where the unexpected behavior occurs. For example, if the server crashes when parsing provider output, reference the JSON-RPC wiring in [`codexAppServerManager.ts`](https://github.com/pingdotgg/t3code/blob/main/codexAppServerManager.ts).

## Summary

Reporting a bug in t3code effectively requires understanding its three-layer architecture: the **Node.js server** managing provider processes, the **React Web UI** consuming WebSocket events, and the **shared TypeScript utilities** handling contracts and logging.

- **Identify the layer** where the bug manifests (provider process, WebSocket routing, or UI rendering).
- **Enable observability** using the guide in [`docs/observability.md`](https://github.com/pingdotgg/t3code/blob/main/docs/observability.md) to capture traces and metrics.
- **Include specific logs** from [`packages/shared/src/effect.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/shared/src/effect.ts) and reference relevant source files like [`codexAppServerManager.ts`](https://github.com/pingdotgg/t3code/blob/main/codexAppServerManager.ts) or [`ChatView.tsx`](https://github.com/pingdotgg/t3code/blob/main/ChatView.tsx).
- **Provide reproduction steps**, environment details, and minimal code examples to speed up triage.

## Frequently Asked Questions

### What information is most important when reporting a t3code server crash?

The most critical details are the **provider process logs** (indicating whether the Codex or Claude binary exited unexpectedly) and the **server traces** showing the JSON-RPC stream state. Include output from [`codexAppServerManager.ts`](https://github.com/pingdotgg/t3code/blob/main/codexAppServerManager.ts) and any `logError` entries from [`packages/shared/src/effect.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/shared/src/effect.ts) that appear in your terminal when the crash occurs.

### How do I enable debug logging for a t3code bug report?

Enable debug logging by following the **Observability Guide** located at [`docs/observability.md`](https://github.com/pingdotgg/t3code/blob/main/docs/observability.md). This document explains how to configure tracing for the server side, which captures the lifecycle of provider sessions managed in [`providerManager.ts`](https://github.com/pingdotgg/t3code/blob/main/providerManager.ts) and the WebSocket events routed through [`wsServer.ts`](https://github.com/pingdotgg/t3code/blob/main/wsServer.ts). Attach the generated trace files to your GitHub issue.

### Where should I report UI rendering issues in t3code?

Report UI rendering issues, such as the chat view not updating or state inconsistency after reconnection, in the main **t3code GitHub Issues** page. When describing the bug, reference [`apps/web/src/components/ChatView.tsx`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/components/ChatView.tsx) (which consumes `orchestration.domainEvent`) and [`apps/web/src/main.tsx`](https://github.com/pingdotgg/t3code/blob/main/apps/web/src/main.tsx) (which handles the WebSocket connection). Include screenshots or screen recordings to demonstrate the visual glitch.

### What should I do if I cannot consistently reproduce a t3code bug?

If you cannot consistently reproduce a bug, still file an issue with the **"intermittent"** label if available, and include as much **environmental context** as possible: your OS, the exact commit hash (`git rev-parse HEAD`), provider versions, and any partial logs from [`packages/shared/src/effect.ts`](https://github.com/pingdotgg/t3code/blob/main/packages/shared/src/effect.ts). Describe the sequence of actions that led to the bug even if it does not always trigger, and mention whether it occurs more frequently under specific conditions (e.g., high load, specific prompt types).