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.

This repository also contains @timazed/codexkit, a separately built and versioned TypeScript backend library (0.2.2) distributed through GitHub Packages. Install it with npm install @timazed/codexkit after configuring GitHub Packages authentication, then import { CodexKitBridgeClient } from "@timazed/codexkit". It executes one CodexKit-prepared text, JSON, or image generation/edit request with supplied authentication. Swift consumers do not need Node or npm. Swift request export and remote routing remain separate integration work; general tool calling remains unsupported. See the TypeScript image API.

Cloud releases use cloud-v* tags and a separate verification/publishing workflow; see GitHub Packages release setup.

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

This prerelease bounds structured recovery, preserves pending attempts when host authorization fails, and adds the separate TypeScript cloud bridge with a local API and signed demo checks. The cloud bridge supports one prepared, tool-free request; public Swift request export, conversation/history routing, and durable remote jobs remain separate work. See the alpha.38 changelog.

• Text and image input, streamed replies, and turn-based typed output with provisional events and a committed result.
• Resumable threads with SQLite or Realm persistence and context compaction.
• App-defined tools with approval gates, skill-policy limits, and bounded opt-in parallel execution.
• Personas, skills, and local memory for app-specific behavior.
• GPT-6.1 Sol, GPT-6 Sol/Luna/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.

ChatGPT account metadata now resolves namespaced claims and repairs persisted unknown metadata during restoration. See account metadata compatibility for precedence, new plan cases, and integration steps.

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 choose the exact version 2.0.0-alpha.38, and select the products your app needs:

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

To build and test the package from a checkout on macOS with Xcode installed:

swift build --force-resolved-versions
swift test --force-resolved-versions

The demos are separate Xcode targets; see Demo Apps for their build and offline verification commands.

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.

Structured recovery preserves a pending attempt when host authorization throws, returning the error without automatic retries or provider credential renewal. Reopen the same handle when the host is ready to authorize it.

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

• Configure models and reasoning, including typed GPT-6.1 Sol, GPT-6 Sol/Luna, and Daybreak identifiers
• Use host-managed sessions, execution handles, and async observation
• Recover saved structured results and authorize bounded replacements
• Stream and validate typed output (text, JSON, JSON Lines, and XML)
• Record codec benchmark and compact-format decision
• Reuse a local Codex session on macOS
• Add memory
• Define personas and skills
• Integrate App Intents, sharing, and background completion
• Configure logging and troubleshoot

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 signed macOS offline checks with python3 Scripts/verify_macos_demo.py --mode smoke. Build and verify the signed iOS simulator app with python3 Scripts/verify_ios_simulator.py --mode smoke. See the demo 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

The iOS and macOS demos display the resolved ChatGPT plan, name, email, and account ID for inspecting sign-in and restoration results.

Follow the demo setup and walkthrough.

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