How to Request a Feature for t3code: The Complete GitHub Workflow Guide

To request a feature for t3code, open a GitHub issue using the repository's built-in Feature request template and complete all required fields including Area, Problem statement, and Smallest useful scope.

The t3code repository maintains a strict, lightweight contribution workflow to ensure the codebase remains focused and maintainable. While the maintainers welcome well-structured feature requests, the project requires you to follow a specific triage process using mandatory form validation. To successfully request a feature for t3code, you need to understand the architectural components and provide concrete details about scope and implementation.

Understanding the t3code Architecture

Before submitting a feature request, identify which component your idea affects. The codebase is organized into distinct areas that determine where implementation would occur:

• apps/web: React + Vite client-side transport and UI (e.g., apps/web/src/wsTransport.ts)
• apps/server: Node.js WebSocket layer and provider orchestration (e.g., apps/server/src/provider/Layers/ProviderService.ts)
• packages/contracts: Shared TypeScript contracts for WebSocket messages (e.g., packages/contracts/src/ws.ts)
• packages/shared: Queue-backed worker implementations (e.g., packages/shared/src/DrainableWorker.ts)

Selecting the correct Area in the issue form ensures maintainers can quickly assess technical impact and route the request to the appropriate module.

Step-by-Step Guide to Submitting a t3code Feature Request

1. Review the Contribution Policy

First, read the [CONTRIBUTING.md](https://github.com/pingdotgg/t3code/blob/main/CONTRIBUTING.md) file. This document explains that while issues are welcomed, the project is not actively accepting unsolicited pull requests. It also defines what the maintainers are least likely to accept, helping you avoid submitting out-of-scope suggestions.

2. Open a New Issue Using the Template

Navigate to the repository's Issues tab and click "New issue". Select the Feature request template. This template is defined in [.github/ISSUE_TEMPLATE/feature_request.yml](https://github.com/pingdotgg/t3code/blob/main/.github/ISSUE_TEMPLATE/feature_request.yml) and enforces required fields through GitHub's form schema validation.

3. Complete the Required Form Fields

The template requires you to fill out specific sections that cannot be bypassed:

• Area: Select from apps/web, apps/server, packages/contracts, packages/shared, Build/CI, or Docs.
• Problem / Use case: Describe the concrete pain point or missing capability.
• Proposed solution: Outline the API, UI, or architectural change you envision.
• Why this matters: Explain the user or developer benefit.
• Smallest useful scope: Define the minimal increment that would solve the problem—this is critical for acceptance.
• Pre-submission checks: Confirm you searched for duplicates and that the request is concrete.

4. Add Supporting Material

Include links to design mock-ups, screenshots, or existing implementation references. If your feature involves risks—such as breaking backward compatibility or exposing sensitive tokens—document these tradeoffs explicitly in the "Risks or tradeoffs" section.

5. Submit and Wait for Triage

Once submitted, the maintainers will apply labels including enhancement and needs-triage. If you are a trusted external contributor listed in .github/VOUCHED.td, the issue will be marked as vouched; otherwise it starts with vouch:unvouched.

Large or unfocused requests are likely to be closed quickly, per the What We Are Least Likely To Accept section of the contributing guide.

6. Optional: Implement the Feature

If invited to implement the feature:

1. Clone the repository and install dependencies with bun install.
2. Consult [.docs/architecture.md](https://github.com/pingdotgg/t3code/blob/main/.docs/architecture.md) to understand the runtime flow.
3. Target the correct module based on your selected Area (e.g., modify apps/web/src/wsTransport.ts for client-side changes).
4. Run the test suite with bun run test to verify existing behavior remains intact.
5. Keep the change small, well-documented, and include before/after screenshots for UI modifications.

Example of a Complete t3code Feature Request

Below is the Markdown structure generated by the issue form. Use this as a reference when drafting your request:

[Feature]: Add "Export session as JSON" to the web UI

## Area

- apps/web

## Problem or use case

I want to download the current conversation state to archive or share it with teammates.

## Proposed solution

Add an "Export" button in the session toolbar. Clicking it serializes the current session model (threads, messages, provider metadata) to a JSON file and triggers a browser download.

## Why this matters

Enables easy backup or migration of sessions without relying on server-side storage.

## Smallest useful scope

Implement the UI button and a client-side `exportSession()` helper that returns `JSON.stringify(sessionState)`.

## Alternatives considered

Copy-pasting JSON from the dev console—manual and error-prone.

## Risks or tradeoffs

Potential exposure of sensitive tokens if session state includes them; auth fields must be redacted before export.

Key Files to Reference When Requesting Features

Understanding these files helps you write precise, actionable feature requests:

Path	Purpose	Relevance to Feature Requests
.github/ISSUE_TEMPLATE/feature_request.yml	Defines required form fields and validation rules	Shows exactly which sections you must complete
CONTRIBUTING.md	Contribution philosophy and triage criteria	Sets expectations for acceptance and review
.docs/architecture.md	High-level runtime diagrams	Helps locate the correct component for your feature
.github/VOUCHED.td	List of trusted external contributors	Determines initial vouch status of your issue
apps/server/src/provider/Layers/ProviderService.ts	Core provider session management	Target for server-side orchestration features
apps/web/src/wsTransport.ts	Client-side WebSocket transport	Target for UI and transport layer features
packages/contracts/src/ws.ts	Shared message contracts	Required when adding new request/response types

Summary

• To request a feature for t3code, you must use the GitHub Issue template located at .github/ISSUE_TEMPLATE/feature_request.yml.
• All required fields are enforced by form validation, including Area, Problem/Use case, Proposed solution, and Smallest useful scope.
• Architecture awareness ensures you select the correct component (apps/web, apps/server, packages/contracts, or packages/shared) and reference specific files like apps/web/src/wsTransport.ts or apps/server/src/provider/Layers/ProviderService.ts.
• Triage process applies labels enhancement and needs-triage, checks your status against .github/VOUCHED.td, and may close vague requests per CONTRIBUTING.md.
• Implementation requires bun install, consultation of .docs/architecture.md, and running bun run test to verify changes.

Frequently Asked Questions

What happens if I submit a feature request without using the template?

GitHub's form validation prevents submission until all required fields in .github/ISSUE_TEMPLATE/feature_request.yml are completed. The template enforces structured input for Area, Problem, Proposed solution, and other critical sections, ensuring maintainers receive consistent information for triage.

Can I submit a pull request implementing my feature request immediately?

No. According to the CONTRIBUTING.md policy, t3code is not actively accepting unsolicited pull requests. You must first submit a feature request issue and wait for maintainer feedback. You will only be invited to implement the feature if the maintainers approve the concept and specifically request code contribution.

What is the "vouch" system mentioned in the triage process?

The vouch system is defined in .github/VOUCHED.td. When you submit a feature request, GitHub Actions checks if your username appears in this file. If listed, your issue receives vouched status, indicating you are a trusted external contributor. If unvouched, the issue remains marked vouch:unvouched until a maintainer manually reviews it.

Which architectural component should I select if my feature involves both the web UI and server logic?

Select the component where the primary complexity resides. If the feature is mainly UI-driven with minor server adjustments, choose apps/web. If it involves significant server-side orchestration or provider runtime changes, select apps/server. You can clarify cross-component impact in the "Proposed solution" section, referencing specific files like apps/web/src/wsTransport.ts and apps/server/src/provider/Layers/ProviderService.ts to demonstrate architectural awareness.

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