Codax

An accessibility-forward native macOS Codex app that talks to a local codex app-server over stdio.

Current State

Codax is still early, but the protocol boundary is no longer partial:

• Transport -> Connection -> Runtime -> ViewModel -> Views
• CodexConnection is the only app-server boundary
• the separate client layer has been deleted
• the connection layer now represents every exported schema in codex-schemas/v0.112.0
• the generated connection surface currently verifies as 433/433 schema exports represented
• CodaxViewModel now starts a real ChatGPT login flow through runtime and tracks pending login state
• thread loading now uses thread/list to persist durable thread summaries, then thread/read to hydrate the selected thread into SwiftData
• inbound server requests are surfaced into view-model-owned pending user-request state
• SwiftData is now the durable read model for thread history, and SwiftUI reads that durable state through @Query
• the sidebar is now a project-rooted NavigationStack that reads Project from SwiftData, pushes project-scoped thread lists, and keeps thread selection driving the content/detail columns
• the detail column is now a compact inspector rail that expands into a detail-local NavigationStack for token usage, reasoning effort, git summary, permissions, and pending requests
• the app shell now owns the toolbar, with New Project, New Thread, and inspector toggle actions at the split-view level

The remaining unfinished work is above the connection layer:

• richer approval, elicitation, and auth-refresh UX
• broader durable projections for account, config, and catalog state
• exec-backed git actions such as commit and commit-and-push
• broader end-user polish and accessibility work

Architecture

Transport

• CodexTransport owns raw Data send/receive/close behavior
• LocalCodexTransport owns local codex app-server --listen stdio:// process launch, stdio framing, stderr capture, and shutdown
• CodexCLIProbe owns local CLI discovery and compatibility checks

Connection

• CodexConnection owns JSON-RPC framing, request correlation, retry behavior, inbound notification routing, and inbound server-request routing
• schema-owned Swift types live under Codax/Controllers/Connection
• the generated file is CodexSchema.generated.swift
• raw string-method request helpers are internal implementation details, not the public API

Runtime And Above

• CodexRuntimeCoordinator is the app-facing session boundary: it starts transport, owns CodexConnection, forwards typed streams, and exposes the typed request surface used by the app
• CodaxPersistenceBridge is the only app-side SwiftData writer: it maps runtime types into Project, ThreadModel, and TurnModel, owns hydration policy, and reconciles summary/detail updates
• CodaxViewModel consumes runtime plus the persistence bridge, keeps only live session state, and owns UI-facing pending login, pending approval, elicitation, alerts, and hydration progress
• SwiftUI views sit above the view model, fetch durable project and thread data from SwiftData with @Query, use the view model only for transient state and actions, and route inspector state through the detail-column navigation stack

Repository Layout

• Codax/Controllers/Transport
  • process launch, stdio transport, and CLI probing
• Codax/Controllers/Connection
  • connection actor, JSON-RPC support types, generated schema graph, typed request methods, notification envelopes, and server-request envelopes
• Codax/Controllers/Runtime
  • runtime ownership and stream forwarding
• Codax/Controllers/Orchestration
  • the CodaxPersistenceBridge and CodaxViewModel app-state layer
• Codax/Views
  • the current SwiftUI shell, now backed by SwiftData queries for durable thread state
• CodaxTests
  • transport, connection, runtime, and orchestration tests
• Docs
  • architecture, coverage, and schema tracking reports

Verification

The connection schema is generated by:

• node Tools/generate_connection_schema.js

The schema coverage gate is:

• node Tools/update_connection_schema_progress.js --verify

Current verified result:

• 433 total exported schema types
• 433 represented in connection Swift
• 0 missing
• 47/47 client requests represented through typed CodexConnection methods
• 44/44 server notifications represented through ServerNotificationEnvelope
• 8/8 server requests represented through ServerRequestEnvelope

Project verification:

• xcodebuild -project /Users/galew/Workspace/Codax/Codax.xcodeproj -scheme Codax -sdk macosx test
• 90 tests passed in 10 suites

Requirements

• macOS
• Xcode
• a local codex CLI capable of running codex app-server --listen stdio://

Project Docs

• ROADMAP.md
• connection-schema-progress.md
• CONNECTION_SCHEMA_REPORT.md
• TRANSPORT_SCHEMA_REPORT.md
• ORCHESTRATION_SCHEMA_REPORT.md
• UI_APP_SERVER_COVERAGE.md