@okcode/monorepo

OK Code

A minimal web GUI for coding agents. Currently supports Codex and Claude, with more providers coming.

Quick Start

npx okcodes

This starts the OK Code server and opens your browser. The app automatically detects which providers you have installed.

Or install the desktop app from the Releases page.

Provider Setup

OK Code supports multiple AI providers. You need at least one configured to start coding.

Option A: OpenAI (Codex CLI)

• Install: npm install -g @openai/codex
• Authenticate: codex login
• Verify: codex login status

If using a custom model provider (Azure OpenAI, Portkey, etc.), configure model_provider in ~/.codex/config.toml instead — no codex login needed.

Option B: Anthropic (Claude Code)

• Install: npm install -g @anthropic-ai/claude-code
• Authenticate: claude auth login
• Verify: claude auth status

[!TIP] You can install both providers and switch between them per session.

Troubleshooting

Run the built-in diagnostic to check your setup:

npx okcodes doctor

If OK Code shows a provider error banner after launch:

Banner message	Fix
"not installed or not on PATH"	Install the CLI (see above), then restart OK Code
"not authenticated"	Run the login command for that provider
"version check failed"	Update the CLI to the latest version

[!NOTE] OK Code launches even without providers configured — you can explore the UI and configure provider binary paths from Settings before starting a session.

Development Setup

Prerequisites: Bun >= 1.3.9, Node.js >= 24.13.1

bun install
bun dev            # start server + web in parallel

This runs the contracts build, then starts the server (port 3773) and web app (port 5733) together via Turbo.

Other dev commands:

bun dev:server     # server only
bun dev:web        # web only
bun dev:desktop    # Electron desktop + web
bun dev:marketing  # Astro marketing site

Quality checks:

bun fmt            # format (oxfmt)
bun lint           # lint (oxlint)
bun typecheck      # type-check all packages
bun run test       # run tests (Vitest)

Architecture

OK Code is a monorepo with four apps and two shared packages, orchestrated by Turbo.

┌─────────────────────────────────┐
│  Browser (React + Vite)         │
│  wsTransport (state machine)    │
│  Typed push decode at boundary  │
└──────────┬──────────────────────┘
           │ ws://localhost:3773
┌──────────▼──────────────────────┐
│  apps/server (Node.js)          │
│  WebSocket + HTTP static server │
│  OrchestrationEngine            │
│  ProviderService                │
└──────────┬──────────────────────┘
           │ JSON-RPC over stdio
┌──────────▼──────────────────────┐
│  codex app-server               │
└─────────────────────────────────┘

The server spawns codex app-server as a child process, communicating over JSON-RPC on stdio. Provider runtime events are normalized into orchestration domain events and pushed to the browser over WebSocket.

Packages

Package	Path	Role
okcodes	apps/server	Node.js CLI and WebSocket server. Wraps Codex app-server, serves the React web app, and manages provider sessions.
@okcode/web	apps/web	React 19 + Vite SPA. Session UX, conversation rendering, and client-side state via Zustand. Connects to the server over WebSocket.
@okcode/desktop	apps/desktop	Electron shell that bundles the server and web app into a native desktop application with auto-updates.
@okcode/marketing	apps/marketing	Astro marketing site.
@okcode/contracts	packages/contracts	Shared Effect schemas and TypeScript contracts for the WebSocket protocol, provider events, orchestration model, and session types. Schema-only — no runtime logic.
@okcode/shared	packages/shared	Shared runtime utilities (git, logging, shell, networking). Uses explicit subpath exports (@okcode/shared/git, etc.) — no barrel index.

Key Technologies

• Runtime: Node.js + Bun
• UI: React 19, Vite 8, Tailwind CSS 4, TanStack Router & Query
• Server: Effect, WebSocket (ws), node-pty
• Desktop: Electron
• Schemas: Effect Schema (in @okcode/contracts)
• Build: Turbo, tsdown
• Lint/Format: oxlint, oxfmt
• Tests: Vitest, Playwright

Event Flow

• The browser opens a WebSocket to the server and registers typed listeners.
• User actions become typed requests sent through the WebSocket transport.
• The server routes requests to ProviderService, which talks to codex app-server over JSON-RPC.
• Provider events are ingested, normalized into orchestration events, and persisted.
• The server pushes domain events back to the browser through an ordered push bus (orchestration.domainEvent channel).
• Async work (checkpoints, command reactions) runs through queue-backed workers and emits typed receipts on completion.

For the full architecture with sequence diagrams, see .docs/architecture.md.

Contributing

Read CONTRIBUTING.md before opening an issue or PR.

Support

Join the Discord.