Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
readme and shit
Theo Browne8c5b8d3b720a
diff --git a/.docs/architecture.md b/.docs/architecture.mdnew file mode 100644index 000000000..e02a5ae80--- /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.mdnew file mode 100644index 000000000..71f1db4e9--- /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.mdnew file mode 100644index 000000000..608374d5d--- /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.mdnew file mode 100644index 000000000..fe84ab02b--- /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.mdnew file mode 100644index 000000000..2206d53ee--- /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.mdnew file mode 100644index 000000000..956b242e1--- /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.mdnew file mode 100644index 000000000..f62af9ffb--- /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 <mac|linux|win> --target <target> --arch <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.mdnew file mode 100644index 000000000..721f094f5--- /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.mdindex d2d87f8f2..4143b5a7f 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--- `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 <mac|linux|win> --target <target> --arch <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.--## 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+Use can also just install the desktop app (it's cooler).-Methods mirror the `NativeApi` interface defined in `@t3tools/contracts`:+Install the [desktop app from the Releases page](https://github.com/pingdotgg/t3code/releases)-- `providers.startSession`, `providers.sendTurn`, `providers.interruptTurn`-- `providers.respondToRequest`, `providers.stopSession`-- `shell.openInEditor`, `server.getConfig`+## Some notes-Codex is the only implemented provider. `claudeCode` is reserved in contracts/UI.+We are very very early in this project. Expect bugs.-## CI quality gates+We are not accepting contributions yet.-- `.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.