CodexCore

Native Swift infrastructure for the Codex app-server: a Swift SDK, a reusable SwiftUI workspace, and a native macOS reference app.

Status: CodexCore 0.11.0 targets macOS 26+, Swift 6.2, and codex-cli 0.148.0 or newer. Protocol types are generated from stable codex-cli 0.148.0. CodexCore opts into experimental app-server capabilities.

Built entirely with Codex

CodexCore was built end to end with Codex, powered by GPT-5.6. The human role was product direction and acceptance; Codex performed the repository analysis, architecture, implementation, testing, debugging, documentation, and release preparation.

Codex was used to:

• reverse-engineer and model the Codex app-server protocol as a typed Swift API;
• design and implement the SDK, reusable SwiftUI layer, and native macOS reference app;
• migrate the runtime across stable Codex CLI releases, generate and validate protocol types, and maintain concurrency invariants;
• run tests, delegate audits to subagents, package the app, capture product screenshots, and rebuild the documentation.

The result is also self-demonstrating: CodexCore hosts Codex workflows, while Codex itself is used to develop and verify CodexCore.

Choose your layer

You want to…	Use	Start here
Run a native Codex client	codex-core-app	Run the app
Add a reusable Codex workspace to a SwiftUI app	CodexCoreUI + CodexCore	Embed the UI
Build your own UI or automation	CodexCore	SDK quick start
Understand or contribute to the runtime	source package	Contributor guide

CodexCoreUI is optional. The reference app is an example host, not a runtime dependency.

What is included

Product	Purpose
CodexCore	Process transport, typed app-server requests, thread/turn leases, canonical state, observation, approvals, dynamic tools, filesystem/process helpers, and protocol models.
CodexCoreUI	SwiftUI workspace, AppKit-backed transcript, composer, prompts, files, terminal, browser, diff previews, plugins, subagents, and theming.
codex-core-app	Native macOS reference application. See the support matrix.
codex-run	Trusted development demo. It auto-approves operations and may write todo.html in its working directory.

Run the reference app

git clone https://github.com/slopwareinc/codexcore.git
cd codexcore
codex --version # checks only the PATH candidate; it must print codex-cli 0.148.0 or newer
swift run codex-core-app

For a normal Finder/Dock application with bundle metadata and the CodexCore icon:

./scripts/package-app.sh --release
open build/CodexCore.app

The packager uses hardened-runtime signing and an installed Developer ID or Apple Development identity when available, preserving macOS privacy grants across local rebuilds. It falls back to ad-hoc signing when no identity exists. Developer ID notarization is opt-in; see the packaging and release guide.

On first launch, sign in with ChatGPT or an API key, choose a workspace, and start a task. CodexCore stores credentials and configuration in ~/.codexcore; it does not reuse ~/.codex implicitly.

See requirements and authentication before troubleshooting runtime or sign-in failures.

Install the libraries

dependencies:[.package(
url:"https://github.com/slopwareinc/codexcore.git",
exact:"0.148.0+codexcore.0.11.0")]

.target(
name:"YourApp",
dependencies:[.product(name:"CodexCore",package:"codexcore"),.product(name:"CodexCoreUI",package:"codexcore") // optional
])

Minimal SDK session

import CodexCore
import Foundation
letcwd=FileManager.default.currentDirectoryPath
letcodex=tryawaitCodex(config:.init(cwd: cwd))defer{Task{await codex.close()}}letthread=tryawait codex.startThread(.init(cwd: cwd))defer{Task{await thread.close()}}letinput=CodexSchemaUserInput(.dictionary(["type":.string("text"),"text":.string("Summarize this project in three bullets."),]))letresult=tryawait thread.runTurn(.init(
input:[input],
threadID: thread.id.rawValue
))foritemin result.items where item.kind ==.agentMessage {iflet text =CodexJSONCoercion.string(from: item.payload["text"]){print(text)}}

This minimal example can wait when app-server asks for approval or input. Production hosts must present or resolve every supported server-request family; see approvals and input.

Architecture

flowchart TD
Host["Host application"] --> UI["CodexCoreUI<br/>Optional SwiftUI presentation"]
Host --> SDK["CodexCore<br/>Typed SDK and runtime"]
UI --> SDK
SDK --> Session["CodexSession actor"]
Session --> Transport["Ordered JSON-RPC transport"]
Session --> Inbox["Server-request inbox<br/>Approvals and user input"]
Session --> Leases["Thread and turn leases"]
Session --> State["Canonical state"]
State --> Observation["Observations and projections"]
Transport --> Server["Pinned Codex app-server subprocess"]

Loading

Read the architecture overview for invariants and ownership boundaries.

Documentation

• Documentation index
• App guide
• SDK lifecycle
• Embedding CodexCoreUI
• Configuration reference
• Support status
• Troubleshooting
• Contributing

Development

swift build --target CodexCoreApp
swift test
python3 -m unittest discover Tools/tests

Protocol bindings are generated. Do not edit Sources/CodexCore/Generated/ or generated request factories by hand; follow protocol upgrades.

License and support

CodexCore is available under the MIT License.

Use GitHub Issues for reproducible bugs and focused feature requests. Do not post credentials or sensitive app-server logs publicly.