A WebSocket-fronted bridge to the claude CLI, plus a typed protocol layer, framework adapters, and a drop-in chat UI. Started as a one-file spike; now a workspace where the wire protocol, the runtime, the reactive client, and the UI ship as separate packages — each with a single, sharp responsibility.
The hard problem the workspace solves: keeping a typed, validated wire-format definition of Claude Code's undocumented stream-json protocol in lock-step with the actual binary, without copying any leaked source. A codegen pipeline extracts the binary's embedded Zod schemas, applies a structured patch DSL for the gaps, and emits arktype runtime schemas + TypeScript types. Integration fixtures captured against a real binary catch behavioural drift; replay tests in CI catch schema regressions. A skill (.claude/skills/regen-protocol/) automates the version-bump loop end-to-end.
bun install
# Pick a reference app — three integration shapes for the same chat UI:
bun --filter './apps/web' dev # drop-in <cc-ws-chat> custom element, bridge as a sibling Bun process
bun --filter './apps/web-react' dev # build-your-own React UI on the cc-ws-react hooks, bridge embedded in the same Bun.serve
bun --filter './apps/web-container' dev # bridge isolated per-session inside a Cloudflare Sandbox container (needs Docker)flowchart LR
subgraph Browser["browser (universal)"]
UI["UI<br/>react / svelte / element"]
Reactive["@cc-ws-client<br/>(nanostores facade)"]
Client["ClaudeClient<br/>(intents + state)"]
Persistence["localStorage<br/>persistence"]
UI --> Reactive
Reactive --> Client
Reactive --> Persistence
end
subgraph Wire["Transport (universal interface)"]
WSC["wsClientTransport"]
end
subgraph Server["server (Bun runtime)"]
WSS["wsServerTransport"]
Spawn["spawnTransport<br/>(Bun.spawn)"]
Claude["claude binary<br/>--input-format stream-json<br/>--output-format stream-json"]
WSS --> Spawn --> Claude
end
Client -- "outbound frames" --> WSC
WSC <-->|"JSONL over WS"| WSS
Claude -- "inbound frames" --> Spawn -- "validate per tier" --> WSS
subgraph Codegen["codegen pipeline (committed snapshots)"]
Extract["extract.ts<br/>(reads binary's Zod runtime)"]
Patches["patches.ts<br/>(structured DSL)"]
Generate["generate.ts<br/>→ schemas / types / dispatch"]
Extract --> Generate
Patches --> Generate
end
Generate -. "@cc-protocol/generated/<ver>" .-> Client
Generate -. "discriminator dispatch map" .-> WSS
| Package | Role | Browser-safe? |
|---|---|---|
@somewhatintelligent/cc-protocol |
Schemas + types + Transport interface + ClaudeClient + ClaudeProcess + universal transports (buffer, inMemoryPair, wsClientTransport). Generated from a pinned Claude binary; no Node/Bun deps in src/. |
✅ — zero Bun.* / node:* references, enforced by grep gate |
@somewhatintelligent/cc-ws-server |
Bun runtime. Bun.spawn-using transports (stdio, ws-server, spawn), plus the WebSocket bridge that pumps frames between a client and a child claude process. |
❌ — Bun runtime only |
@somewhatintelligent/cc-ws-client |
Thin nanostores facade over ClaudeClient. Preserves the CcAtoms contract downstream packages expect; adds localStorage persistence. |
✅ |
@somewhatintelligent/cc-ws-react |
useCcSession hook (re-export of nanostores useStore over the atoms). |
✅ |
@somewhatintelligent/cc-ws-svelte |
Typed context injection over the atoms (which already satisfy Svelte's store contract). | ✅ |
@somewhatintelligent/cc-ws-element |
<cc-ws-chat> custom element. Shadow-DOM-isolated; drop-in for any framework. |
✅ |
| App | Stack | Notes |
|---|---|---|
apps/web |
Svelte 5 + Vite | Mounts <cc-ws-chat> from packages/element. Runs the bridge concurrently via bun --hot ../../packages/server/src/server.ts. |
apps/web-react |
React 19 + Bun.serve |
Single-process app: Bun serves HTML + bundled client.tsx and hosts the bridge at /ws. |
apps/web-container |
Svelte 5 + Vite + @cloudflare/sandbox |
Bridge runs inside a per-session Cloudflare Sandbox container; worker proxies WS via wsConnect. Mirrors slopbox's container substrate (per-session credential injection, GitHub PAT-as-outbound-proxy, idempotent /init) without auth / D1 / dashboards. |
flowchart TB
cc-protocol["@cc-protocol<br/>universal core"]
cc-ws-server["@cc-ws-server<br/>Bun runtime"]
cc-ws-client["@cc-ws-client<br/>nanostores facade"]
cc-ws-react["@cc-ws-react"]
cc-ws-svelte["@cc-ws-svelte"]
cc-ws-element["@cc-ws-element"]
apps-web["apps/web<br/>(svelte)"]
apps-web-react["apps/web-react"]
apps-web-container["apps/web-container<br/>(svelte + cf sandbox)"]
arktype["arktype"]
nanostores["nanostores"]
cc-protocol --> arktype
cc-ws-client --> cc-protocol
cc-ws-client --> nanostores
cc-ws-server --> cc-protocol
cc-ws-react --> cc-ws-client
cc-ws-svelte --> cc-ws-client
cc-ws-element --> cc-ws-svelte
apps-web --> cc-ws-element
apps-web --> cc-ws-server
apps-web-react --> cc-ws-react
apps-web-react --> cc-ws-server
apps-web-container --> cc-ws-element
apps-web-container -. "runs cc-ws-server inside CF Sandbox container" .-> cc-ws-server
User types a message in the Svelte UI; here's what happens on the wire:
sequenceDiagram
autonumber
participant UI as UI (Header/Composer)
participant Reactive as @cc-ws-client<br/>(reactive.ts)
participant Client as ClaudeClient
participant WSC as wsClientTransport
participant WS as WebSocket
participant WSS as wsServerTransport
participant Spawn as spawnTransport
participant Bin as claude binary
UI->>Reactive: createCcSession({url})
Reactive->>Client: new ClaudeClient(transport)
Reactive->>WSC: wsClientTransport(url, {reconnect})
WSC-->>WS: ws.open
WSC-->>Reactive: onOpen
Reactive->>Client: respawn() → builds _local:respawn frame
Client->>WSC: send({_local:"respawn", args:[...]})
WSC->>WS: JSON.stringify → ws.send
WS->>WSS: message
WSS->>Spawn: Bun.spawn(claude, args)
Spawn-->>WSS: pid, transport ready
WSS->>WS: {_local:"respawnResult", ok:true}
UI->>Client: client.sendUserMessage("hi")
Client->>WSC: {type:"user", message, parent_tool_use_id:null}
WSC->>WS: send
WS->>WSS: message → forward
WSS->>Spawn: write to stdin
Spawn->>Bin: JSONL over stdin
Bin->>Spawn: system/init, assistant frames, stream_event, ...
Spawn-->>WSS: validated per tier (off / discriminator / strict)
WSS->>WS: ws.send each frame
WS->>WSC: messages
WSC->>Client: onFrame
Client->>Client: StateHolder.applyInbound(frame)<br/>updates messages, tasks, shell, hooks, mode, ...
Client-->>Reactive: onStateChange(snapshot)
Reactive->>Reactive: atoms.set(...) per field
Reactive-->>UI: $messages, $init, $tasks etc. re-render
- Schemas + types pinned to a specific
@anthropic-ai/claude-codebinary version (codegen/version.ts:ACTIVE_VERSION). - Mechanical regeneration from the binary's embedded Zod schemas — see
codegen/extract.ts. - Structured patch DSL for fields the structural extractor can't auto-resolve (
codegen/patch-dsl.ts). - Discriminator-keyed dispatch map for O(1) validation lookup.
- Three runtime validation tiers (
off/discriminator/strict) selectable perClaudeProcess. - Browser-safety enforced structurally:
@cc-protocol/src/has zeroBun.*/node:*references (CI grep gate).
- Messages — streaming-bubble assembly from
stream_event(message_start→content_block_start/_delta/_stop→message_stop). - Tasks — full lifecycle from
system/task_started→task_progress→task_notification/task_updated, with sub-agent task routing viaparent_tool_use_id. - Shell entries —
system/local_command_outputaggregation with rolling output and stop-detection. - Hook events —
hook_started→hook_progress→hook_responsechains. - Pending permissions — UI-shape queue from
can_use_toolcontrol_requests; consumers respond viaclient.respondToPermission(id, decision). - Mode tracking —
set_permission_moderound-trip withactiveMode/pendingMode/modeError. - Model tracking —
set_modelround-trip withactiveModel/pendingModel/modelError. - Session lifecycle — start (
initialize), end (end_session), respawn (caller-managed instance disposal + recreation with a fresh transport).
bufferTransport— pure in-memory; tests script wire traffic withfeed()/drain().inMemoryPair— returns[a, b]wherea.send → b.onFrameand vice versa; enablesClaudeClient ↔ ClaudeProcessE2E tests with zero IO.wsClientTransport(url, opts?)— universal WebSocket client; opt-in exponential-backoff reconnect.stdioTransport— JSONL framing over arbitrary streams (in@cc-ws-server).wsServerTransport— BunServerWebSocketadapter (in@cc-ws-server).spawnTransport—Bun.spawnsclaudewith canonical args; returnsTransport & { pid, exited, kill }(in@cc-ws-server).
- Extractor anchors on Zod-method shape, not lazy-wrapper aliases — survives bundler renames across binary versions (verified across
xH/v → CH/ybetween 2.1.129 and 2.1.139). Auto-detects multiple Zod namespaces. Captures per-field RHS expression strings for type translation. - Patch DSL (
fieldType/addField/removeField/renameSchema/resolveAnon/discriminantHint) — every patch carries areasonfor audit trail. - Generator emits
schemas.ts(arktype) +types.ts(typeof X.infer) +dispatch.ts(discriminator map). All carry@generatedheaders and/* @__PURE__ */annotations for tree-shaking. - Integration test harness drives the binary through a zero-cost test catalog (only side-effect-free control requests); captures fixtures as committed
.jsonlfiles. - Replay-fixtures validates committed fixtures against committed schemas — runs in CI without needing the binary.
- Drift detection via
extract.ts comparebetween snapshots; produces a markdown diff committed undercodegen/snapshots/drift/. - Coverage tracking —
coverage.jsonper snapshot records{ typed, partial, unknown }field counts. - Failure log — append-only
failures.mdper snapshot records everyunknown-fallthrough and validation rejection, withreason/attempted-fix/resolution. - One-command checkpoint —
bun codegen/checkpoint.tsruns all 14 gates in sequence with a coloured pass/fail table.
.claude/skills/regen-protocol/SKILL.md encodes the version-bump workflow as a 13-step procedure. Triggers: "bump claude protocol", "regen claude schemas", "claude binary updated". Walks: extract → diff → seed patches → codegen → integration capture → checkpoint → changeset.
flowchart LR
Bin["claude binary<br/>(pinned version)"]
Canonical["snapshots/<ver>/<br/>canonical.json"]
Patches["snapshots/<ver>/<br/>patches.ts"]
Fixtures["snapshots/<ver>/<br/>integration-fixtures/*.jsonl"]
Generated["generated/<ver>/<br/>schemas.ts<br/>types.ts<br/>dispatch.ts"]
Replay["replay-fixtures<br/>(CI gate)"]
Pkg["packages/protocol<br/>(published)"]
Bin -->|"extract.ts"| Canonical
Bin -->|"integration/run-tests.ts"| Fixtures
Canonical -->|"generate.ts"| Generated
Patches -->|"generate.ts"| Generated
Generated --> Pkg
Generated -.->|"validate"| Replay
Fixtures -.->|"validate against"| Replay
# Svelte reference (Vite + bridge concurrently)
bun --filter './apps/web' dev
# React reference (Bun serves HTML + bridge from one process)
bun --filter './apps/web-react' dev
# Cloudflare Sandbox container reference (Svelte + bridge inside a CF Sandbox)
bun --filter './apps/web-container' dev # needs Docker (or OrbStack / Colima)
# Build the <cc-ws-chat> embed bundle
bun --filter '@somewhatintelligent/cc-ws-element' build
# All-packages tests
bun test
# Per-package typechecks
bunx tsc --noEmit -p packages/protocol/tsconfig.json
bunx tsc --noEmit -p packages/server/tsconfig.json
# Codegen checkpoint (extractor + codegen + integration + replay + verify-package)
bun codegen/checkpoint.ts
# Live binary E2E (opt-in)
CC_PROTOCOL_LIVE_BINARY=1 bun test packages/server/__tests__/live.test.tsInvoke the regen-protocol skill (.claude/skills/regen-protocol/SKILL.md). It runs:
- Branch + clean state check.
claude --versionvsACTIVE_VERSION.- New extraction.
- Drift report against the previous snapshot.
- Patch seed (copy forward).
- Codegen + coverage report.
- Patch-authoring loop with the user / AI (the leaked source at
../claude-code/src/entrypoints/sdk/is consulted for shape only; no source ever copied). - Integration fixture capture against the new binary.
- Loop steps 6–8 until clean.
bun codegen/checkpoint.ts— all gates green.bun changeset— semver per drift severity.bun codegen/verify-package.ts— pre-publish guard.- Hand-off summary.
See codegen/README.md for the pipeline mechanics.
- Designed for local dev / sandboxed deployment. The bridge has no auth — put it behind something (Cloudflare Sandbox container, an authenticated proxy, an SSO mesh) before exposing it.
- One WS connection = one
claudechild = one session. - Relies on the host already being OAuth-authed at
~/.claude/.credentials.json(orANTHROPIC_API_KEYset). - Schemas pinned to one binary version at a time; consumers run against any binary version but type-level guarantees only hold against the pinned one.
The schemas in packages/protocol/generated/ are derived from observation of a Claude binary you legally installed — they're the output of extracting embedded Zod runtime values from the bundled JS inside the standalone executable. No leaked source is copied into this repo. The leaked Claude Code source (when used at all, during patch authoring) is consulted as a reading reference for structural shape only, and each patch carries a reason field naming the file:line it was derived from. See codegen/README.md for details.