| author |  Theo Browne <me@t3.gg> 2026-03-05 23:07:59-08:00 |
| committer | Theo Browne <me@t3.gg> 2026-03-05 23:07:59-08:00 |
| log | 8c5b8d3b720a82de1c77fe3aa32bde7a5ff36325 |
| tree | 2c7e5c42438536d26a2b97c446c4c31ceaf8201f |
| parent | 010ba70561cff75af0188213e87f8c418b0c3b81 |
| signature | Commit is signed but in an unrecognized format. |
readme and shit
9 files changed, 131 insertions(+), 121 deletions(-)
.docs/architecture.md created+21
| ... | @@ -0,0 +1,21 @@ | ||
| 1 | # Architecture | ||
| 2 | |||
| 3 | T3 Code runs as a **Node.js WebSocket server** that wraps `codex app-server` (JSON-RPC over stdio) and serves a React web app. | ||
| 4 | |||
| 5 | ``` | ||
| 6 | ┌─────────────────────────────────┐ | ||
| 7 | │ Browser (React + Vite) │ | ||
| 8 | │ Connected via WebSocket │ | ||
| 9 | └──────────┬──────────────────────┘ | ||
| 10 | │ ws://localhost:3773 | ||
| 11 | ┌──────────▼──────────────────────┐ | ||
| 12 | │ apps/server (Node.js) │ | ||
| 13 | │ WebSocket + HTTP static server │ | ||
| 14 | │ ProviderManager │ | ||
| 15 | │ CodexAppServerManager │ | ||
| 16 | └──────────┬──────────────────────┘ | ||
| 17 | │ JSON-RPC over stdio | ||
| 18 | ┌──────────▼──────────────────────┐ | ||
| 19 | │ codex app-server │ | ||
| 20 | └─────────────────────────────────┘ | ||
| 21 | ``` | ||
.docs/ci.md created+6
| ... | @@ -0,0 +1,6 @@ | ||
| 1 | # CI quality gates | ||
| 2 | |||
| 3 | - `.github/workflows/ci.yml` runs `bun run lint`, `bun run typecheck`, and `bun run test` on pull requests and pushes to `main`. | ||
| 4 | - `.github/workflows/release.yml` builds macOS (`arm64` and `x64`), Linux (`x64`), and Windows (`x64`) desktop artifacts from a single `v*.*.*` tag and publishes one GitHub release. | ||
| 5 | - The release workflow auto-enables signing only when secrets are present: Apple credentials for macOS and Azure Trusted Signing credentials for Windows. Without secrets, it still releases unsigned artifacts. | ||
| 6 | - See `docs/release.md` for full release/signing setup checklist. | ||
.docs/codex-prerequisites.md created+5
| ... | @@ -0,0 +1,5 @@ | ||
| 1 | # Codex prerequisites | ||
| 2 | |||
| 3 | - Install Codex CLI so `codex` is on your PATH. | ||
| 4 | - Authenticate Codex before running T3 Code (for example via API key or ChatGPT auth supported by Codex). | ||
| 5 | - T3 Code starts the server via `codex app-server` per session. | ||
.docs/provider-architecture.md created+14
| ... | @@ -0,0 +1,14 @@ | ||
| 1 | # Provider architecture | ||
| 2 | |||
| 3 | The web app communicates with the server via WebSocket using a simple JSON-RPC-style protocol: | ||
| 4 | |||
| 5 | - **Request/Response**: `{ id, method, params }` → `{ id, result }` or `{ id, error }` | ||
| 6 | - **Push events**: `{ type: "push", channel, data }` for orchestration read-model updates | ||
| 7 | |||
| 8 | Methods mirror the `NativeApi` interface defined in `@t3tools/contracts`: | ||
| 9 | |||
| 10 | - `providers.startSession`, `providers.sendTurn`, `providers.interruptTurn` | ||
| 11 | - `providers.respondToRequest`, `providers.stopSession` | ||
| 12 | - `shell.openInEditor`, `server.getConfig` | ||
| 13 | |||
| 14 | Codex is the only implemented provider. `claudeCode` is reserved in contracts/UI. | ||
.docs/quick-start.md created+22
| ... | @@ -0,0 +1,22 @@ | ||
| 1 | # Quick start | ||
| 2 | |||
| 3 | ```bash | ||
| 4 | # Development (with hot reload) | ||
| 5 | bun run dev | ||
| 6 | |||
| 7 | # Desktop development | ||
| 8 | bun run dev:desktop | ||
| 9 | |||
| 10 | # Desktop development on an isolated port set | ||
| 11 | T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop | ||
| 12 | |||
| 13 | # Production | ||
| 14 | bun run build | ||
| 15 | bun run start | ||
| 16 | |||
| 17 | # Build a shareable macOS .dmg (arm64 by default) | ||
| 18 | bun run dist:desktop:dmg | ||
| 19 | |||
| 20 | # Or from any project directory after publishing: | ||
| 21 | npx t3 | ||
| 22 | ``` | ||
.docs/runtime-modes.md created+6
| ... | @@ -0,0 +1,6 @@ | ||
| 1 | # Runtime modes | ||
| 2 | |||
| 3 | T3 Code has a global runtime mode switch in the chat toolbar: | ||
| 4 | |||
| 5 | - **Full access** (default): starts sessions with `approvalPolicy: never` and `sandboxMode: danger-full-access`. | ||
| 6 | - **Supervised**: starts sessions with `approvalPolicy: on-request` and `sandboxMode: workspace-write`, then prompts in-app for command/file approvals. | ||
.docs/scripts.md created+42
| ... | @@ -0,0 +1,42 @@ | ||
| 1 | # Scripts | ||
| 2 | |||
| 3 | - `bun run dev` — Starts contracts, server, and web in `turbo watch` mode. | ||
| 4 | - `bun run dev:server` — Starts just the WebSocket server (uses Bun TypeScript execution). | ||
| 5 | - `bun run dev:web` — Starts just the Vite dev server for the web app. | ||
| 6 | - Dev commands default `T3CODE_STATE_DIR` to `~/.t3/dev` to keep dev state isolated from desktop/prod state. | ||
| 7 | - Override server CLI-equivalent flags from root dev commands with `--`, for example: | ||
| 8 | `bun run dev -- --state-dir ~/.t3/another-dev-state` | ||
| 9 | - `bun run start` — Runs the production server (serves built web app as static files). | ||
| 10 | - `bun run build` — Builds contracts, web app, and server through Turbo. | ||
| 11 | - `bun run typecheck` — Strict TypeScript checks for all packages. | ||
| 12 | - `bun run test` — Runs workspace tests. | ||
| 13 | - `bun run dist:desktop:artifact -- --platform <mac|linux|win> --target <target> --arch <arch>` — Builds a desktop artifact for a specific platform/target/arch. | ||
| 14 | - `bun run dist:desktop:dmg` — Builds a shareable macOS `.dmg` into `./release`. | ||
| 15 | - `bun run dist:desktop:dmg:x64` — Builds an Intel macOS `.dmg`. | ||
| 16 | - `bun run dist:desktop:linux` — Builds a Linux AppImage into `./release`. | ||
| 17 | - `bun run dist:desktop:win` — Builds a Windows NSIS installer into `./release`. | ||
| 18 | |||
| 19 | ## Desktop `.dmg` packaging notes | ||
| 20 | |||
| 21 | - Default build is unsigned/not notarized for local sharing. | ||
| 22 | - The DMG build uses `assets/macos-icon-1024.png` as the production app icon source. | ||
| 23 | - Desktop production windows load the bundled UI from `t3://app/index.html` (not a `127.0.0.1` document URL). | ||
| 24 | - Desktop packaging includes `apps/server/dist` (the `t3` backend) and starts it on loopback with an auth token for WebSocket/API traffic. | ||
| 25 | - Your tester can still open it on macOS by right-clicking the app and choosing **Open** on first launch. | ||
| 26 | - To keep staging files for debugging package contents, run: `bun run dist:desktop:dmg -- --keep-stage` | ||
| 27 | - To allow code-signing/notarization when configured in CI/secrets, add: `--signed`. | ||
| 28 | - Windows `--signed` uses Azure Trusted Signing and expects: | ||
| 29 | `AZURE_TRUSTED_SIGNING_ENDPOINT`, `AZURE_TRUSTED_SIGNING_ACCOUNT_NAME`, | ||
| 30 | `AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME`, and `AZURE_TRUSTED_SIGNING_PUBLISHER_NAME`. | ||
| 31 | - Azure authentication env vars are also required (for example service principal with secret): | ||
| 32 | `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`. | ||
| 33 | |||
| 34 | ## Running multiple dev instances | ||
| 35 | |||
| 36 | Set `T3CODE_DEV_INSTANCE` to any value to deterministically shift all dev ports together. | ||
| 37 | |||
| 38 | - Default ports: server `3773`, web `5733` | ||
| 39 | - Shifted ports: `base + offset` (offset is hashed from `T3CODE_DEV_INSTANCE`) | ||
| 40 | - Example: `T3CODE_DEV_INSTANCE=branch-a bun run dev:desktop` | ||
| 41 | |||
| 42 | If you want full control instead of hashing, set `T3CODE_PORT_OFFSET` to a numeric offset. | ||
.docs/workspace-layout.md created+6
| ... | @@ -0,0 +1,6 @@ | ||
| 1 | # Workspace layout | ||
| 2 | |||
| 3 | - `/apps/server`: Node.js WebSocket server. Wraps Codex app-server, serves the built web app, and opens the browser on start. | ||
| 4 | - `/apps/web`: React + Vite UI. Session control, conversation, and provider event rendering. Connects to the server via WebSocket. | ||
| 5 | - `/apps/desktop`: Electron shell. Spawns a desktop-scoped `t3` backend process and loads the shared web app. | ||
| 6 | - `/packages/contracts`: Shared Zod schemas and TypeScript contracts for provider events, WebSocket protocol, and model/session types. | ||
README.md+9-121
| ... | @@ -2,135 +2,23 @@ | ... | @@ -2,135 +2,23 @@ |
| 2 | 2 | ||
| 3 | T3 Code is a minimal web GUI for coding agents. Currently Codex-first, with Claude Code support coming soon. | 3 | T3 Code is a minimal web GUI for coding agents. Currently Codex-first, with Claude Code support coming soon. |
| 4 | 4 | ||
| 5 | Run `npx t3` in any project directory to launch the web interface. | 5 | ## How to use |
| 6 | Run `bun run dev:desktop` to launch the Electron desktop app in this monorepo. | ||
| 7 | 6 | ||
| 8 | ## Architecture | 7 | > [!WARNING] |
| 9 | 8 | > You need to have [Codex CLI](https://github.com/openai/codex) installed and authorized for T3 Code to work. | |
| 10 | T3 Code runs as a **Node.js WebSocket server** that wraps `codex app-server` (JSON-RPC over stdio) and serves a React web app. | ||
| 11 | |||
| 12 | ``` | ||
| 13 | ┌─────────────────────────────────┐ | ||
| 14 | │ Browser (React + Vite) │ | ||
| 15 | │ Connected via WebSocket │ | ||
| 16 | └──────────┬──────────────────────┘ | ||
| 17 | │ ws://localhost:3773 | ||
| 18 | ┌──────────▼──────────────────────┐ | ||
| 19 | │ apps/server (Node.js) │ | ||
| 20 | │ WebSocket + HTTP static server │ | ||
| 21 | │ ProviderManager │ | ||
| 22 | │ CodexAppServerManager │ | ||
| 23 | └──────────┬──────────────────────┘ | ||
| 24 | │ JSON-RPC over stdio | ||
| 25 | ┌──────────▼──────────────────────┐ | ||
| 26 | │ codex app-server │ | ||
| 27 | └─────────────────────────────────┘ | ||
| 28 | ``` | ||
| 29 | |||
| 30 | ## Workspace layout | ||
| 31 | |||
| 32 | - `/apps/server`: Node.js WebSocket server. Wraps Codex app-server, serves the built web app, and opens the browser on start. | ||
| 33 | - `/apps/web`: React + Vite UI. Session control, conversation, and provider event rendering. Connects to the server via WebSocket. | ||
| 34 | - `/apps/desktop`: Electron shell. Spawns a desktop-scoped `t3` backend process and loads the shared web app. | ||
| 35 | - `/packages/contracts`: Shared Zod schemas and TypeScript contracts for provider events, WebSocket protocol, and model/session types. | ||
| 36 | |||
| 37 | ## Codex prerequisites | ||
| 38 | |||
| 39 | - Install Codex CLI so `codex` is on your PATH. | ||
| 40 | - Authenticate Codex before running T3 Code (for example via API key or ChatGPT auth supported by Codex). | ||
| 41 | - T3 Code starts the server via `codex app-server` per session. | ||
| 42 | |||
| 43 | ## Quick start | ||
| 44 | 9 | ||
| 45 | ```bash | 10 | ```bash |
| 46 | # Development (with hot reload) | ||
| 47 | bun run dev | ||
| 48 | |||
| 49 | # Desktop development | ||
| 50 | bun run dev:desktop | ||
| 51 | |||
| 52 | # Desktop development on an isolated port set | ||
| 53 | T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop | ||
| 54 | |||
| 55 | # Production | ||
| 56 | bun run build | ||
| 57 | bun run start | ||
| 58 | |||
| 59 | # Build a shareable macOS .dmg (arm64 by default) | ||
| 60 | bun run dist:desktop:dmg | ||
| 61 | |||
| 62 | # Or from any project directory after publishing: | ||
| 63 | npx t3 | 11 | npx t3 |
| 64 | ``` | 12 | ``` |
| 65 | 13 | ||
| 66 | ## Scripts | 14 | Use can also just install the desktop app (it's cooler). |
| 67 | |||
| 68 | - `bun run dev` — Starts contracts, server, and web in `turbo watch` mode. | ||
| 69 | - `bun run dev:server` — Starts just the WebSocket server (uses Bun TypeScript execution). | ||
| 70 | - `bun run dev:web` — Starts just the Vite dev server for the web app. | ||
| 71 | - Dev commands default `T3CODE_STATE_DIR` to `~/.t3/dev` to keep dev state isolated from desktop/prod state. | ||
| 72 | - Override server CLI-equivalent flags from root dev commands with `--`, for example: | ||
| 73 | `bun run dev -- --state-dir ~/.t3/another-dev-state` | ||
| 74 | - `bun run start` — Runs the production server (serves built web app as static files). | ||
| 75 | - `bun run build` — Builds contracts, web app, and server through Turbo. | ||
| 76 | - `bun run typecheck` — Strict TypeScript checks for all packages. | ||
| 77 | - `bun run test` — Runs workspace tests. | ||
| 78 | - `bun run dist:desktop:artifact -- --platform <mac|linux|win> --target <target> --arch <arch>` — Builds a desktop artifact for a specific platform/target/arch. | ||
| 79 | - `bun run dist:desktop:dmg` — Builds a shareable macOS `.dmg` into `./release`. | ||
| 80 | - `bun run dist:desktop:dmg:x64` — Builds an Intel macOS `.dmg`. | ||
| 81 | - `bun run dist:desktop:linux` — Builds a Linux AppImage into `./release`. | ||
| 82 | - `bun run dist:desktop:win` — Builds a Windows NSIS installer into `./release`. | ||
| 83 | |||
| 84 | ### Desktop `.dmg` packaging notes | ||
| 85 | |||
| 86 | - Default build is unsigned/not notarized for local sharing. | ||
| 87 | - The DMG build uses `assets/macos-icon-1024.png` as the production app icon source. | ||
| 88 | - Desktop production windows load the bundled UI from `t3://app/index.html` (not a `127.0.0.1` document URL). | ||
| 89 | - Desktop packaging includes `apps/server/dist` (the `t3` backend) and starts it on loopback with an auth token for WebSocket/API traffic. | ||
| 90 | - Your tester can still open it on macOS by right-clicking the app and choosing **Open** on first launch. | ||
| 91 | - To keep staging files for debugging package contents, run: `bun run dist:desktop:dmg -- --keep-stage` | ||
| 92 | - To allow code-signing/notarization when configured in CI/secrets, add: `--signed`. | ||
| 93 | - Windows `--signed` uses Azure Trusted Signing and expects: | ||
| 94 | `AZURE_TRUSTED_SIGNING_ENDPOINT`, `AZURE_TRUSTED_SIGNING_ACCOUNT_NAME`, | ||
| 95 | `AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME`, and `AZURE_TRUSTED_SIGNING_PUBLISHER_NAME`. | ||
| 96 | - Azure authentication env vars are also required (for example service principal with secret): | ||
| 97 | `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`. | ||
| 98 | |||
| 99 | ### Running multiple dev instances | ||
| 100 | |||
| 101 | Set `T3CODE_DEV_INSTANCE` to any value to deterministically shift all dev ports together. | ||
| 102 | |||
| 103 | - Default ports: server `3773`, web `5733` | ||
| 104 | - Shifted ports: `base + offset` (offset is hashed from `T3CODE_DEV_INSTANCE`) | ||
| 105 | - Example: `T3CODE_DEV_INSTANCE=branch-a bun run dev:desktop` | ||
| 106 | |||
| 107 | If you want full control instead of hashing, set `T3CODE_PORT_OFFSET` to a numeric offset. | ||
| 108 | |||
| 109 | ## Runtime modes | ||
| 110 | |||
| 111 | T3 Code has a global runtime mode switch in the chat toolbar: | ||
| 112 | |||
| 113 | - **Full access** (default): starts sessions with `approvalPolicy: never` and `sandboxMode: danger-full-access`. | ||
| 114 | - **Supervised**: starts sessions with `approvalPolicy: on-request` and `sandboxMode: workspace-write`, then prompts in-app for command/file approvals. | ||
| 115 | |||
| 116 | ## Provider architecture | ||
| 117 | |||
| 118 | The web app communicates with the server via WebSocket using a simple JSON-RPC-style protocol: | ||
| 119 | |||
| 120 | - **Request/Response**: `{ id, method, params }` → `{ id, result }` or `{ id, error }` | ||
| 121 | - **Push events**: `{ type: "push", channel, data }` for orchestration read-model updates | ||
| 122 | 15 | ||
| 123 | Methods mirror the `NativeApi` interface defined in `@t3tools/contracts`: | 16 | Install the [desktop app from the Releases page](https://github.com/pingdotgg/t3code/releases) |
| 124 | 17 | ||
| 125 | - `providers.startSession`, `providers.sendTurn`, `providers.interruptTurn` | 18 | ## Some notes |
| 126 | - `providers.respondToRequest`, `providers.stopSession` | ||
| 127 | - `shell.openInEditor`, `server.getConfig` | ||
| 128 | 19 | ||
| 129 | Codex is the only implemented provider. `claudeCode` is reserved in contracts/UI. | 20 | We are very very early in this project. Expect bugs. |
| 130 | 21 | ||
| 131 | ## CI quality gates | 22 | We are not accepting contributions yet. |
| 132 | 23 | ||
| 133 | - `.github/workflows/ci.yml` runs `bun run lint`, `bun run typecheck`, and `bun run test` on pull requests and pushes to `main`. | 24 | Discord link coming soon. |
| 134 | - `.github/workflows/release.yml` builds macOS (`arm64` and `x64`), Linux (`x64`), and Windows (`x64`) desktop artifacts from a single `v*.*.*` tag and publishes one GitHub release. | ||
| 135 | - The release workflow auto-enables signing only when secrets are present: Apple credentials for macOS and Azure Trusted Signing credentials for Windows. Without secrets, it still releases unsigned artifacts. | ||
| 136 | - See `docs/release.md` for full release/signing setup checklist. |