The gateway

The gateway is the spawn server: the orchestrator that everything else talks to. The TUI, web UI, and desktop app are all clients of this one server, connecting over WebSocket to exchange domain events. There is a single orchestrator and many clients.

The server is built on the Effect TS framework, which shapes how its services, layers, and event-sourced core fit together.

What the server does

• WebSocket server — clients (TUI, web, desktop) connect and exchange domain events.
• Provider supervision — spawns and supervises child agent CLIs as child processes, one git worktree per session, and streams their events back.
• Event-sourced orchestration — the core pattern is commands → decider → events → read model. Sessions and threads carry full event history (work logs, approvals, diffs).
• Persistence — SQLite.
• Git worktree management — each session runs in its own isolated worktree.
• CodingRouter — a service that shells out to the local ONNX classifier to decide harness and model for a task (see Routing).
• CoordinationService — the file registry and change-feed sidecar that keeps parallel agents aware of each other (see Coordination).

Architecture

TUI / web / desktop  ↔ WebSocket ↔  spawn server (orchestrator)
                                      ├─ CodingRouter (→ local ONNX classifier)
                                      ├─ CoordinationService (file registry, change feeds)
                                      ├─ Orchestration (commands → decider → events → read model)
                                      └─ Provider Drivers (Claude, Codex, Cursor, OpenCode, Grok…)
                                           └── child agent CLIs (one git worktree per session)

The server sits in the middle. Clients never talk to agent CLIs directly—they send commands to the server, and the server supervises the underlying processes, routes work, coordinates parallel agents, and streams events back. Schemas for everything—domain events, provider kinds, coordination types—live in a shared contracts package, which is the place to extend when adding new provider kinds or coordination types.

Provider drivers

Each agent harness is integrated through a clean ProviderDriver<Config> interface, paired with per-harness adapters and Effect Layers. A driver's create(...) returns a provider instance that bundles a snapshot, an adapter, and text generation. The built-in drivers are Codex, Claude, Cursor, and OpenCode, with Grok planned.

A session maps to a supervised child CLI: the server launches the corresponding agent CLI as a child process in the session's own git worktree, supervises it, and streams its events back to clients.

Orchestration

The orchestration core is event-sourced. Every change flows through commands → decider → events → read model: a command is evaluated by a decider, which emits events, and the read model is rebuilt from those events. Because nothing is mutated in place, sessions and threads carry their full event history—work logs, approvals, and diffs are all part of the record rather than derived state that can be lost.

Running the gateway

In development, build first and then start the server:

bun run build
bun run --cwd apps/server start -- ...