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.

The optional @timazed/codexkit npm package lets Node.js backends execute CodexKit-prepared text, structured JSON, and image generation/edit requests. It provides a focused execution bridge for your own middleware. Swift consumers do not need Node or npm.

The latest stable release is v2.2.0.
For upgrades from 1.x or earlier 2.0 alpha snapshots, read the
migration notes. The 1.1.0 documentation
remains available for existing 1.x integrations.

Version 2.0 brings typed and turn-based streaming output, durable recovery,
separate SQLite and Realm adapters, remote execution, image generation, and
usage telemetry. Version 2.1 adds optional image progress estimates, GPT-6.1 Terra
support, safety-recourse metadata, and more reliable simulator verification.
Version 2.2 adds opt-in client session export/import with versioned payloads,
expiry validation, and explicit credential replacement.
See the 2.2.0 changelog and
performance report.

Capabilities

• 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.

Cloud execution with npm

@timazed/codexkit exists so a TypeScript backend can execute requests prepared by CodexKit from an API route or worker. It supplies transport, response parsing, output validation, and typed failures. For example, a backend can generate a story, produce schema-validated game data, or generate/edit an image, then store the result for an app to retrieve later. Your backend supplies the queue, durable job storage, and result lookup needed for work to continue after an app disconnects.

The current Cloud release is 0.2.5, distributed through GitHub Packages. It supports Node.js 22 and 24, CommonJS and ESM imports, and TypeScript declarations, with zero runtime dependencies. It has its own build, tests, and version because it serves Node backends independently of the Swift SDK. Cloud releases use cloud-v* tags; Swift releases use v* tags.

What the npm package supports

After configuring GitHub Packages authentication, install the package in your backend:

npm install @timazed/codexkit

Your integration supplies the prepared provider bytes, SHA-256 digest, routing identifiers, and separate per-call authentication. Both text and JSON requests use this entry point; the format comes from the prepared body:

import { CodexKitBridgeClient } from "@timazed/codexkit";

const client = new CodexKitBridgeClient();
const result = await client.execute({ preparedRequest, authentication });
// result.outputText contains the completed text or validated JSON text.

See the backend guide and supported text subset, API route example, and results/progress contract.

Current limits and host responsibilities

• A limited request executor: text/JSON requests must be self-contained and tool-free. General tool calling, web search, image input through execute, assistant-history migration, previous-response/conversation references, and provider background mode are unsupported. JSON validation supports a bounded schema subset, not every JSON Schema assertion.
• No full agent runtime: the npm package does not provide Swift's conversation persistence, personas, skills, memory, tool approvals, or typed JSON Lines/XML decoding. It preserves the prepared model, reasoning, format, and request bytes; it does not discover/select models, repair requests, or generate fallback answers.
• One provider attempt per call: there are no automatic retries, sign-in flows, credential refresh, or built-in generation deadlines. The backend owns caller authorization, credential custody, deadlines, retry decisions, job deduplication, storage, and notification delivery. Cancelling local transport does not prove the provider stopped generating.

Swift apps can submit already-prepared packets to mp-api-compatible middleware with CodexRemoteExecutionClient and choose silent or regular completion pushes. Runtime request export and automatic conversation/result integration remain separate work; installing the npm package does not supply a hosted service or those integrations. See remote execution and completion pushes.

To explore text, JSON, and images locally, start npm run dev:api in packages/codexkit. In either Debug demo, open Structured → Local Cloud → Remote Execution and choose Verify All Remote Features for the 16-job fixture matrix. See the demo guide. For package publishing, see Cloud release setup.

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 choose the exact version 2.2.0, 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.

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.

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.

Documentation

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
• Execute prepared text, JSON, and image requests in a Node backend
• Submit remote requests and choose completion pushes
• 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
• Export and import a supplied client session
• 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 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.

Project

• Structured validation and backend completion
• Usage telemetry: token details, partial coverage, retries and saved receipt reuse.
• Changelog and release conventions
• Contributing
• Security policy