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

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 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 – starts a provider-specific app-server process and wires its JSON-RPC streams.
• 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 – entry point that connects to the WebSocket server.
• 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 – lightweight effect helpers (logDebug, logError) used throughout the codebase.
• 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).
• 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	Starts provider processes; crashes here appear as provider died.
Provider lifecycle	apps/server/src/providerManager.ts	Handles session state, logging, and error propagation.
WebSocket routing	apps/server/src/wsServer.ts	Translates internal events to client-side channels (orchestration.domainEvent).
UI entry point	apps/web/src/main.tsx	Connects to the server; socket errors surface here.
Chat view component	apps/web/src/components/ChatView.tsx	Renders provider output; UI glitches are often traced here.
Shared effect helpers	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	Defines message shapes; validation errors point to contract mismatches.
Observability guide	docs/observability.md	Shows how to enable tracing/metrics for server-side bugs.
Contributing instructions	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.

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 to capture traces and metrics.
• Include specific logs from packages/shared/src/effect.ts and reference relevant source files like codexAppServerManager.ts or 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 and any logError entries from 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. This document explains how to configure tracing for the server side, which captures the lifecycle of provider sessions managed in providerManager.ts and the WebSocket events routed through 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 (which consumes orchestration.domainEvent) and 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. 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).

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