CodexKit

CodexKit is a Swift SDK for embedding Codex-style agents in iOS 17+ and macOS 14+ apps. It provides ChatGPT sign-in, persistent conversations, streaming, host-defined tools, and optional local memory.

main tracks the upcoming 2.0 development line; the latest prerelease is v2.0.0-alpha.30. For the stable release, use the v1.1.0 documentation. Upgrading an alpha integration? Read the migration notes.

This prerelease adds local Codex session reuse and the native macOS demo. See the release verification report for validation and publication status.

Capabilities

• Text and image input, streamed replies, and typed structured output.
• Resumable threads with SQLite or Realm persistence and context compaction.
• App-defined tools with approval gates and opt-in parallel execution.
• Personas, skills, and local memory for app-specific behavior.
• GPT-6 Astra identifiers, account model discovery, and reported usage limits.
• Provider progress, message phases, input added to active turns, and interruption.
• Browser OAuth, device-code sign-in, and read-only reuse of local Codex sessions on macOS.

Your app owns the tools and user interface. The built-in backend uses ChatGPT account access; model availability depends on the account. See the feature matrix for the full supported surface.

Installation

Swift 6.1 or newer is required; Xcode projects require Xcode 16.3 or newer. The deployment targets remain iOS 17 and macOS 14.

Add https://github.com/timazed/CodexKit as a Swift package dependency in Xcode and select the products your app needs:

Product	Purpose
CodexKit	Core runtime, authentication, backend, tools, and memory APIs
CodexKitUI	Optional SwiftUI helpers for runtime state and prompts
CodexKitSQLite	SQLite persistence through GRDB
CodexKitRealm	Realm persistence through RealmSwift

Choose one persistence adapter for normal application use. See persistence integration for package configuration, storage locations, and migration.

Quickstart

The example uses SQLite for persistence. Present device-code prompts and tool approvals from the coordinators in your SwiftUI app; see authentication on iOS.

1. Add this package to your Xcode project.
2. Build an AgentRuntime with auth, secure storage, backend, approvals, and state store.
3. Sign in, create a thread, and send a message.

import CodexKit
import CodexKitSQLite
import CodexKitUI

let approvalInbox = ApprovalInbox()
let deviceCodeCoordinator = DeviceCodePromptCoordinator()

let runtime = try AgentRuntime(configuration: .init(
    authProvider: try ChatGPTAuthProvider(
        method: .deviceCode,
        deviceCodePresenter: deviceCodeCoordinator
    ),
    secureStore: KeychainSessionSecureStore(
        service: "CodexKit.ChatGPTSession",
        account: "main"
    ),
    backend: CodexResponsesBackend(
        configuration: .init(
            model: .gpt56Sol,
            reasoningEffort: .low,
            enableWebSearch: true
        )
    ),
    approvalPresenter: approvalInbox,
    stateStore: try SQLiteRuntimeStateStore()
))

let _ = try await runtime.signIn()
let thread = try await runtime.createThread(
    title: "First Chat",
    configuration: AgentThreadConfiguration(
        model: .gpt56Sol,
        reasoningEffort: .low
    )
)
let stream = try await runtime.stream(
    Request(text: "Hello from Apple platforms."),
    in: thread.id
)
for try await event in stream {
    if case let .assistantMessageDelta(_, _, text) = event {
        print(text, terminator: "")
    }
}

For macOS applications that reuse an accessible local Codex login, see local session discovery and lifecycle.

For typed replies and attachments, see Messaging and images. For model discovery, parallel tools, progress, and turn controls, see Runtime progress, tools, and turn control.

Signed-in accounts expose an optional account.name and account.displayName, which falls back to email. See account names.

Turns use bounded event queues and configurable execution limits. The default runtime duration is five minutes, including approval waits; see event buffering and execution limits for longer workflows.

Documentation

The documentation index contains the full guide list, core concepts, and architecture overview. Common next steps:

• Configure models and reasoning
• Use host-managed sessions, execution handles, and async observation
• Recover saved structured results and authorize bounded replacements
• Reuse a local Codex session on macOS
• Add memory
• Define personas and skills
• Integrate App Intents, sharing, and background completion
• Configure logging and troubleshoot

Demo Apps

The native macOS demo includes local Codex session reuse, browser OAuth, device-code sign-in, streaming chat, tools and approvals, typed output, memory, and File/SQLite/Realm persistence. Both demos share DemoApp/CodexKitDemo.xcodeproj: select the CodexKitMacDemo scheme for macOS or CodexKitIOSDemo for iOS. Build and run the macOS offline checks with python3 Scripts/verify_macos_demo.py. See the macOS walkthrough.

The checked-in iOS app consumes the local package and demonstrates chat, structured output, memory, and Health Coach flows. It includes model refresh, account usage, live progress, Add to turn, Stop, and a Parallel Lookups example.

open DemoApp/CodexKitDemo.xcodeproj

Follow the demo setup and walkthrough.

Project

• Streaming validation and backend completion
• Changelog and release conventions
• Contributing
• Security policy