Codax

An accessibility-forward native macOS Codex client that uses your locally installed codex & subscription via codex app-server.

Codax is in early alpha. The protocol and architecture layers are ahead of the app shell and UI, which are still placeholder-level. This repo is best read today (March 10, 2026) as an active construction site: more contributor-facing project than polished end-user app.

Table of Contents

• What Codax Is
• Current Status
• Why This Project Exists
• Architecture At A Glance
• Repository Layout
• Requirements
• Getting Started
• Project Documentation
• Roadmap
• Contributing
• Notes

What Codax Is

Codax is a native macOS client for the Codex app-server protocol. It is being built to work with your existing local Codex installation rather than replacing that tooling with a separate hosted interface or a closed workflow.

The project is explicitly accessibility-forward. The long-term goal is a usable, native, multi-pane Codex desktop app that is workable with assistive technology, and feels best-in-class for anyone's 'day-to-day engineering workflow on macOS. Maybe even on iOS~

Current Status

The repository already has real protocol-facing work in place:

• hardened stdio transport and local process-launch foundations
• an actor-based JSON-RPC connection layer with request and response correlation plus tested retry handling for retryable overloads
• initial typed client wrappers for current app-server methods, including client-owned account and login DTOs
• startup compatibility gating for Codex CLI 0.111.x and 0.112.x
• an early NavigationSplitView shell backed by a shared environment-injected CodaxOrchestrator
• layer reports grounded in the current v0.112.0 schema baseline, with an explicit v0.111.0 -> v0.112.0 diff report

The app-facing layers are still early:

• orchestration is now partially real, but not complete yet
• the NavigationSplitView shell is implemented in a transitional state and still needs broader pane behavior, polish, and accessibility work
• UX polish and the full accessibility pass are still in progress, or roadmapped for the near future.
• transport, connection, client, orchestration, and compatibility coverage now exist under CodaxTests, while deeper client DTO validation and broader notification coverage remain open.
• the test target is now organized by Transport, Connection, Client, and Orchestration

Why This Project Exists

Codax exists to make agentic coding more accessible and less confining. The project is aimed at developers who want a native desktop client that respects their existing tools, local workflows, and project environments instead of forcing them into a simplified or walled-garden experience.

Just as important, the project is being shaped around accessibility from the start. I know very well that the only way to get it right is to bake it in from day-one. I don't just want to put Codex in a working UI that performs well and looks nice. I don't just want to add high-value features that I'm tired of waiting for in the big names' products. I want to bring Codex (and many other tools, stay tuned~) to everyone like me who gets left behind by tech advancements year after year. Decade after decade. I want people such as myself to have great tools that don't exclude them, slow them down, frustrate them, or cause them physical pain.

Architecture At A Glance

The codebase is currently organized into a small set of explicit layers:

• Transport

  • CodexTransport defines raw transport behavior as a protocol.
  • CodexTransport+Stdio is the current actor-based stdio transport implementation.
  • CodexProcess launches the local codex app-server process and owns the hardened stdio lifecycle.
  • CodexCLIProbe detects the installed CLI path and compatibility range before connect flows proceed.

• Connection

  • CodexConnection owns actor-based JSON-RPC framing, request correlation, retry handling, and inbound routing.

• Client

  • CodexClient provides typed wrappers over the generic connection layer.

• Orchestration

  • CodaxOrchestrator is the shared app-facing session owner and is injected through the SwiftUI environment.
  • AuthCoordinator remains the auth-side effect boundary.

• Views

  • SwiftUI views now live in an early three-pane shell and read shared state directly from CodaxOrchestrator.
  • ContentViewModel remains only for pane-local draft state; shared app state does not flow through pane models.

CodaxTests is now organized by layer, with transport, connection, client, and orchestration suites split under dedicated directories.

Repository Layout

The main areas of the repository are:

• Codax/Controllers/Transport
  • transport protocols, stdio transport, CLI probing, websocket placeholder support, and process-launch types
• Codax/Controllers/Connection
  • JSON-RPC message types, connection state, and request-routing behavior
• Codax/Controllers/Client
  • typed request wrappers, inbound message lifting, and server-request handling
• Codax/Controllers/Orchestration
  • orchestration runtime, app session state, and auth coordination types
• Codax/Views
  • the current SwiftUI split-view shell
• CodaxTests
  • layer-organized test target with Transport, Connection, Client, and Orchestration suites
• Docs
  • schema and protocol reports used to ground the implementation

Requirements

Codax currently assumes:

• macOS
• Xcode
• codex CLI installed locally to run the app-server over stdio

The repository does not currently present itself as a packaged or stable released app.

Getting Started

1. Open in Xcode.
2. Build the Codax app target.
3. Run the app from Xcode.

Current expectations:

• the app launches into an early NavigationSplitView shell
• protocol-facing layers are ahead of the UI
• some end-to-end app flows are now real, but broader thread, login, and pane behavior is still incomplete

If you are contributing to protocol work, the schema reports and roadmap are the best starting points after opening the project.

Project Documentation

Project docs currently worth reading first:

• ROADMAP.md
• TRANSPORT_SCHEMA_REPORT.md
• CONNECTION_SCHEMA_REPORT.md
• CLIENT_SCHEMA_REPORT.md
• CLIENT_THREAD_TURN_ITEM_AUDIT.md
• ORCHESTRATION_SCHEMA_REPORT.md
• SCHEMA_DIFF_REPORT_v0.111.0_to_v0.112.0.md

These documents describe the milestone sequencing, the current layer boundaries, the v0.112.0 schema framing, and the remaining implementation gaps still being closed.

Roadmap

The roadmap is maintained in ROADMAP.md.

At a high level, the project is moving in bounded slices:

• transport
• connection
• client
• orchestration
• UI shell
• accessibility and UX refinement

Later milestones cover compatibility management, thread and code summarization features, and performance work.

Contributing

Contribution guidance lives in CONTRIBUTING.md.

The most useful contributions right now are likely to be in:

• broader server-notification coverage and client DTO validation
• orchestration refinement
• the current NavigationSplitView shell and pane behavior
• accessibility-first UI and interaction work
• documentation and report alignment

Notes

• Codax is currently an early, pre-alpha project.
• The app is still early alpha and UI-incomplete, even though the protocol-facing layers are already fairly real.
• Codax is currently compatibility-gated for Codex CLI 0.111.x and 0.112.x.
• Local Codex version and compatibility handling is still being built out beyond the current supported range.
• The current UI shell is real but transitional; it should not be mistaken for a finished product surface.
• The layer reports are currently framed against the v0.112.0 schema baseline, and the dedicated diff report preserves the v0.111.0 -> v0.112.0 change context.
• The repository does not yet document a polished release or distribution workflow.
• The current README is intentionally contributor-first because the architecture is further along than the end-user product surface.