Skip to content

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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.