Codax

A very under-construction, accessibility-forward Codex GUI for macOS. It talks to your local codex app-server over stdio, no extra subscription needed. It's currently in the middle of a migration from an older CodaxViewModel app layer to CodaxOrchestrator.

Current State

What is solid in the checked-in code today:

• CodexTransport, LocalCodexTransport, and CodexCLIProbe provide the local process and stdio boundary.
• CodexConnection is the only typed app-server boundary.
• the connection layer represents every exported schema in codex-schemas/v0.114.0
• the generated connection surface currently verifies as 497/497 schema exports represented
• CodexRuntimeCoordinator starts transport, owns CodexConnection, forwards typed notifications, and forwards typed server requests
• CodaxOrchestrator exists as the current top-level app-facing observable object
• the app shell already uses NavigationSplitView

What is visibly mid-transition:

• several docs still describe the older CodaxViewModel architecture as if it were current
• orchestration tests still target CodaxViewModel
• some view files are placeholders or still reference CodaxViewModel
• the checked-in UI does not yet support all of the inspector, toolbar, SwiftData @Query, and project-navigation behavior previously described in the docs

This means the protocol and schema layers are ahead of the app shell. Documentation in this repo should be read as transition-aware unless a file is generated from schema coverage data.

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

• CodexRuntimeCoordinator is the app-facing session boundary for the current runtime layer
• it starts transport, owns CodexConnection, forwards typed streams, and exposes the typed request surface used by higher layers

Orchestration And UI

• CodaxOrchestrator is the checked-in observable app object used by CodaxApp.swift
• the repo is still migrating off the older CodaxViewModel design; some files and tests still reflect that older shape
• SwiftUI views above the app shell are not yet uniformly migrated, so they should not be treated as a completed reference architecture

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
  • CodaxOrchestrator and request-surface forwarding extensions
• Codax/SwiftData
  • durable model types used by the in-progress app layer
• Codax/Views
  • the current SwiftUI shell and the migration-in-progress view tree
• CodaxTests
  • transport, connection, runtime, and older 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 documented coverage result:

• 497 total exported schema types
• 497 represented in connection Swift
• 0 missing
• 52/52 client requests represented through typed CodexConnection methods
• 47/47 server notifications represented through ServerNotificationEnvelope
• 9/9 server requests represented through ServerRequestEnvelope

Version support policy:

• until codex reaches v1.x.x, Codax aims to track the latest released codex app-server schema version rather than maintain a broad pre-v1 compatibility matrix
• compatibility gating in code and tests may temporarily stay pinned to a narrower verified CLI range while migration work catches up

Project checks commonly used in this repo:

• node Tools/generate_connection_schema.js
• node Tools/update_connection_schema_progress.js --verify
• xcodebuild -project /Users/galew/Workspace/Codax/Codax.xcodeproj -scheme Codax -sdk macosx build
• xcodebuild -project /Users/galew/Workspace/Codax/Codax.xcodeproj -scheme Codax -destination 'platform=macOS' test

The checked-in docs previously claimed a passing test count, but this README intentionally does not restate that number until it is re-verified against the current repo state.

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