From 8c5b8d3b720a82de1c77fe3aa32bde7a5ff36325 Mon Sep 17 00:00:00 2001 From: Theo Browne Date: Thu, 5 Mar 2026 23:07:59 -0800 Subject: [PATCH] readme and shit --- .docs/architecture.md | 21 ++++++ .docs/ci.md | 6 ++ .docs/codex-prerequisites.md | 5 ++ .docs/provider-architecture.md | 14 ++++ .docs/quick-start.md | 22 ++++++ .docs/runtime-modes.md | 6 ++ .docs/scripts.md | 42 +++++++++++ .docs/workspace-layout.md | 6 ++ README.md | 130 +++------------------------------ 9 files changed, 131 insertions(+), 121 deletions(-) create mode 100644 .docs/architecture.md create mode 100644 .docs/ci.md create mode 100644 .docs/codex-prerequisites.md create mode 100644 .docs/provider-architecture.md create mode 100644 .docs/quick-start.md create mode 100644 .docs/runtime-modes.md create mode 100644 .docs/scripts.md create mode 100644 .docs/workspace-layout.md diff --git a/.docs/architecture.md b/.docs/architecture.md new file mode 100644 index 0000000000000000000000000000000000000000..e02a5ae804d5431db42233f8cbd2f885d4e1a28b --- /dev/null +++ b/.docs/architecture.md @@ -0,0 +1,21 @@ +# Architecture + +T3 Code runs as a **Node.js WebSocket server** that wraps `codex app-server` (JSON-RPC over stdio) and serves a React web app. + +``` +┌─────────────────────────────────┐ +│ Browser (React + Vite) │ +│ Connected via WebSocket │ +└──────────┬──────────────────────┘ + │ ws://localhost:3773 +┌──────────▼──────────────────────┐ +│ apps/server (Node.js) │ +│ WebSocket + HTTP static server │ +│ ProviderManager │ +│ CodexAppServerManager │ +└──────────┬──────────────────────┘ + │ JSON-RPC over stdio +┌──────────▼──────────────────────┐ +│ codex app-server │ +└─────────────────────────────────┘ +``` diff --git a/.docs/ci.md b/.docs/ci.md new file mode 100644 index 0000000000000000000000000000000000000000..71f1db4e91e7c660f018b348a67eca8af59b52f6 --- /dev/null +++ b/.docs/ci.md @@ -0,0 +1,6 @@ +# CI quality gates + +- `.github/workflows/ci.yml` runs `bun run lint`, `bun run typecheck`, and `bun run test` on pull requests and pushes to `main`. +- `.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. +- 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. +- See `docs/release.md` for full release/signing setup checklist. diff --git a/.docs/codex-prerequisites.md b/.docs/codex-prerequisites.md new file mode 100644 index 0000000000000000000000000000000000000000..608374d5db957a049f4675605ee750185e6f9a46 --- /dev/null +++ b/.docs/codex-prerequisites.md @@ -0,0 +1,5 @@ +# Codex prerequisites + +- Install Codex CLI so `codex` is on your PATH. +- Authenticate Codex before running T3 Code (for example via API key or ChatGPT auth supported by Codex). +- T3 Code starts the server via `codex app-server` per session. diff --git a/.docs/provider-architecture.md b/.docs/provider-architecture.md new file mode 100644 index 0000000000000000000000000000000000000000..fe84ab02b1ae0818b9956ea10099b17e6c8acbee --- /dev/null +++ b/.docs/provider-architecture.md @@ -0,0 +1,14 @@ +# Provider architecture + +The web app communicates with the server via WebSocket using a simple JSON-RPC-style protocol: + +- **Request/Response**: `{ id, method, params }` → `{ id, result }` or `{ id, error }` +- **Push events**: `{ type: "push", channel, data }` for orchestration read-model updates + +Methods mirror the `NativeApi` interface defined in `@t3tools/contracts`: + +- `providers.startSession`, `providers.sendTurn`, `providers.interruptTurn` +- `providers.respondToRequest`, `providers.stopSession` +- `shell.openInEditor`, `server.getConfig` + +Codex is the only implemented provider. `claudeCode` is reserved in contracts/UI. diff --git a/.docs/quick-start.md b/.docs/quick-start.md new file mode 100644 index 0000000000000000000000000000000000000000..2206d53ee580bde5e6cc33e1b83cb940152f0a57 --- /dev/null +++ b/.docs/quick-start.md @@ -0,0 +1,22 @@ +# Quick start + +```bash +# Development (with hot reload) +bun run dev + +# Desktop development +bun run dev:desktop + +# Desktop development on an isolated port set +T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop + +# Production +bun run build +bun run start + +# Build a shareable macOS .dmg (arm64 by default) +bun run dist:desktop:dmg + +# Or from any project directory after publishing: +npx t3 +``` diff --git a/.docs/runtime-modes.md b/.docs/runtime-modes.md new file mode 100644 index 0000000000000000000000000000000000000000..956b242e1c14a9c3b3d9dda6b8f43123d06687a8 --- /dev/null +++ b/.docs/runtime-modes.md @@ -0,0 +1,6 @@ +# Runtime modes + +T3 Code has a global runtime mode switch in the chat toolbar: + +- **Full access** (default): starts sessions with `approvalPolicy: never` and `sandboxMode: danger-full-access`. +- **Supervised**: starts sessions with `approvalPolicy: on-request` and `sandboxMode: workspace-write`, then prompts in-app for command/file approvals. diff --git a/.docs/scripts.md b/.docs/scripts.md new file mode 100644 index 0000000000000000000000000000000000000000..f62af9ffb4227835b8e82673b557ad45df863e94 --- /dev/null +++ b/.docs/scripts.md @@ -0,0 +1,42 @@ +# Scripts + +- `bun run dev` — Starts contracts, server, and web in `turbo watch` mode. +- `bun run dev:server` — Starts just the WebSocket server (uses Bun TypeScript execution). +- `bun run dev:web` — Starts just the Vite dev server for the web app. +- Dev commands default `T3CODE_STATE_DIR` to `~/.t3/dev` to keep dev state isolated from desktop/prod state. +- Override server CLI-equivalent flags from root dev commands with `--`, for example: + `bun run dev -- --state-dir ~/.t3/another-dev-state` +- `bun run start` — Runs the production server (serves built web app as static files). +- `bun run build` — Builds contracts, web app, and server through Turbo. +- `bun run typecheck` — Strict TypeScript checks for all packages. +- `bun run test` — Runs workspace tests. +- `bun run dist:desktop:artifact -- --platform --target --arch ` — Builds a desktop artifact for a specific platform/target/arch. +- `bun run dist:desktop:dmg` — Builds a shareable macOS `.dmg` into `./release`. +- `bun run dist:desktop:dmg:x64` — Builds an Intel macOS `.dmg`. +- `bun run dist:desktop:linux` — Builds a Linux AppImage into `./release`. +- `bun run dist:desktop:win` — Builds a Windows NSIS installer into `./release`. + +## Desktop `.dmg` packaging notes + +- Default build is unsigned/not notarized for local sharing. +- The DMG build uses `assets/macos-icon-1024.png` as the production app icon source. +- Desktop production windows load the bundled UI from `t3://app/index.html` (not a `127.0.0.1` document URL). +- Desktop packaging includes `apps/server/dist` (the `t3` backend) and starts it on loopback with an auth token for WebSocket/API traffic. +- Your tester can still open it on macOS by right-clicking the app and choosing **Open** on first launch. +- To keep staging files for debugging package contents, run: `bun run dist:desktop:dmg -- --keep-stage` +- To allow code-signing/notarization when configured in CI/secrets, add: `--signed`. +- Windows `--signed` uses Azure Trusted Signing and expects: + `AZURE_TRUSTED_SIGNING_ENDPOINT`, `AZURE_TRUSTED_SIGNING_ACCOUNT_NAME`, + `AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME`, and `AZURE_TRUSTED_SIGNING_PUBLISHER_NAME`. +- Azure authentication env vars are also required (for example service principal with secret): + `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`. + +## Running multiple dev instances + +Set `T3CODE_DEV_INSTANCE` to any value to deterministically shift all dev ports together. + +- Default ports: server `3773`, web `5733` +- Shifted ports: `base + offset` (offset is hashed from `T3CODE_DEV_INSTANCE`) +- Example: `T3CODE_DEV_INSTANCE=branch-a bun run dev:desktop` + +If you want full control instead of hashing, set `T3CODE_PORT_OFFSET` to a numeric offset. diff --git a/.docs/workspace-layout.md b/.docs/workspace-layout.md new file mode 100644 index 0000000000000000000000000000000000000000..721f094f528e1ffec02584e5c777a57b4c01d9c7 --- /dev/null +++ b/.docs/workspace-layout.md @@ -0,0 +1,6 @@ +# Workspace layout + +- `/apps/server`: Node.js WebSocket server. Wraps Codex app-server, serves the built web app, and opens the browser on start. +- `/apps/web`: React + Vite UI. Session control, conversation, and provider event rendering. Connects to the server via WebSocket. +- `/apps/desktop`: Electron shell. Spawns a desktop-scoped `t3` backend process and loads the shared web app. +- `/packages/contracts`: Shared Zod schemas and TypeScript contracts for provider events, WebSocket protocol, and model/session types. diff --git a/README.md b/README.md index d2d87f8f25f399eba9e1c472a08af57a8ff4f7aa..4143b5a7f41b663da25d705d9cb0c730144d2c5e 100644 --- a/README.md +++ b/README.md @@ -2,135 +2,23 @@ T3 Code is a minimal web GUI for coding agents. Currently Codex-first, with Claude Code support coming soon. -Run `npx t3` in any project directory to launch the web interface. -Run `bun run dev:desktop` to launch the Electron desktop app in this monorepo. +## How to use -## Architecture - -T3 Code runs as a **Node.js WebSocket server** that wraps `codex app-server` (JSON-RPC over stdio) and serves a React web app. - -``` -┌─────────────────────────────────┐ -│ Browser (React + Vite) │ -│ Connected via WebSocket │ -└──────────┬──────────────────────┘ - │ ws://localhost:3773 -┌──────────▼──────────────────────┐ -│ apps/server (Node.js) │ -│ WebSocket + HTTP static server │ -│ ProviderManager │ -│ CodexAppServerManager │ -└──────────┬──────────────────────┘ - │ JSON-RPC over stdio -┌──────────▼──────────────────────┐ -│ codex app-server │ -└─────────────────────────────────┘ -``` - -## Workspace layout - -- `/apps/server`: Node.js WebSocket server. Wraps Codex app-server, serves the built web app, and opens the browser on start. -- `/apps/web`: React + Vite UI. Session control, conversation, and provider event rendering. Connects to the server via WebSocket. -- `/apps/desktop`: Electron shell. Spawns a desktop-scoped `t3` backend process and loads the shared web app. -- `/packages/contracts`: Shared Zod schemas and TypeScript contracts for provider events, WebSocket protocol, and model/session types. - -## Codex prerequisites - -- Install Codex CLI so `codex` is on your PATH. -- Authenticate Codex before running T3 Code (for example via API key or ChatGPT auth supported by Codex). -- T3 Code starts the server via `codex app-server` per session. - -## Quick start +> [!WARNING] +> You need to have [Codex CLI](https://github.com/openai/codex) installed and authorized for T3 Code to work. ```bash -# Development (with hot reload) -bun run dev - -# Desktop development -bun run dev:desktop - -# Desktop development on an isolated port set -T3CODE_DEV_INSTANCE=feature-xyz bun run dev:desktop - -# Production -bun run build -bun run start - -# Build a shareable macOS .dmg (arm64 by default) -bun run dist:desktop:dmg - -# Or from any project directory after publishing: npx t3 ``` -## Scripts +Use can also just install the desktop app (it's cooler). -- `bun run dev` — Starts contracts, server, and web in `turbo watch` mode. -- `bun run dev:server` — Starts just the WebSocket server (uses Bun TypeScript execution). -- `bun run dev:web` — Starts just the Vite dev server for the web app. -- Dev commands default `T3CODE_STATE_DIR` to `~/.t3/dev` to keep dev state isolated from desktop/prod state. -- Override server CLI-equivalent flags from root dev commands with `--`, for example: - `bun run dev -- --state-dir ~/.t3/another-dev-state` -- `bun run start` — Runs the production server (serves built web app as static files). -- `bun run build` — Builds contracts, web app, and server through Turbo. -- `bun run typecheck` — Strict TypeScript checks for all packages. -- `bun run test` — Runs workspace tests. -- `bun run dist:desktop:artifact -- --platform --target --arch ` — Builds a desktop artifact for a specific platform/target/arch. -- `bun run dist:desktop:dmg` — Builds a shareable macOS `.dmg` into `./release`. -- `bun run dist:desktop:dmg:x64` — Builds an Intel macOS `.dmg`. -- `bun run dist:desktop:linux` — Builds a Linux AppImage into `./release`. -- `bun run dist:desktop:win` — Builds a Windows NSIS installer into `./release`. +Install the [desktop app from the Releases page](https://github.com/pingdotgg/t3code/releases) -### Desktop `.dmg` packaging notes +## Some notes -- Default build is unsigned/not notarized for local sharing. -- The DMG build uses `assets/macos-icon-1024.png` as the production app icon source. -- Desktop production windows load the bundled UI from `t3://app/index.html` (not a `127.0.0.1` document URL). -- Desktop packaging includes `apps/server/dist` (the `t3` backend) and starts it on loopback with an auth token for WebSocket/API traffic. -- Your tester can still open it on macOS by right-clicking the app and choosing **Open** on first launch. -- To keep staging files for debugging package contents, run: `bun run dist:desktop:dmg -- --keep-stage` -- To allow code-signing/notarization when configured in CI/secrets, add: `--signed`. -- Windows `--signed` uses Azure Trusted Signing and expects: - `AZURE_TRUSTED_SIGNING_ENDPOINT`, `AZURE_TRUSTED_SIGNING_ACCOUNT_NAME`, - `AZURE_TRUSTED_SIGNING_CERTIFICATE_PROFILE_NAME`, and `AZURE_TRUSTED_SIGNING_PUBLISHER_NAME`. -- Azure authentication env vars are also required (for example service principal with secret): - `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`. +We are very very early in this project. Expect bugs. -### Running multiple dev instances +We are not accepting contributions yet. -Set `T3CODE_DEV_INSTANCE` to any value to deterministically shift all dev ports together. - -- Default ports: server `3773`, web `5733` -- Shifted ports: `base + offset` (offset is hashed from `T3CODE_DEV_INSTANCE`) -- Example: `T3CODE_DEV_INSTANCE=branch-a bun run dev:desktop` - -If you want full control instead of hashing, set `T3CODE_PORT_OFFSET` to a numeric offset. - -## Runtime modes - -T3 Code has a global runtime mode switch in the chat toolbar: - -- **Full access** (default): starts sessions with `approvalPolicy: never` and `sandboxMode: danger-full-access`. -- **Supervised**: starts sessions with `approvalPolicy: on-request` and `sandboxMode: workspace-write`, then prompts in-app for command/file approvals. - -## Provider architecture - -The web app communicates with the server via WebSocket using a simple JSON-RPC-style protocol: - -- **Request/Response**: `{ id, method, params }` → `{ id, result }` or `{ id, error }` -- **Push events**: `{ type: "push", channel, data }` for orchestration read-model updates - -Methods mirror the `NativeApi` interface defined in `@t3tools/contracts`: - -- `providers.startSession`, `providers.sendTurn`, `providers.interruptTurn` -- `providers.respondToRequest`, `providers.stopSession` -- `shell.openInEditor`, `server.getConfig` - -Codex is the only implemented provider. `claudeCode` is reserved in contracts/UI. - -## CI quality gates - -- `.github/workflows/ci.yml` runs `bun run lint`, `bun run typecheck`, and `bun run test` on pull requests and pushes to `main`. -- `.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. -- 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. -- See `docs/release.md` for full release/signing setup checklist. +Discord link coming soon. -- 2.54.0