CodexKit

CodexKit is an experimental Swift package for embedding Codex agents in iOS and macOS apps.

The v1 package exposes a small Swift API:

• API-key auth
• thread-style conversations
• streamed assistant output
• app-provided Swift tools
• App Store-safe defaults

It also includes a sample app, Field Notes, that consumes CodexKit through a local SwiftPM dependency and lets an embedded agent search, create, tag, and update notes through registered Swift tools.

Status

This repo is an early scaffold for a Swift API backed by the upstream Codex runtime through codexkit-ffi. It should not grow a separate OpenAI API agent loop.

The upstream OpenAI Codex repository is tracked as a submodule under Upstream/codex so the Rust/Codex adapter work can stay close to upstream without vendoring or forking it.

The feasibility check so far:

• the real upstream runtime surface is codex-core: ThreadManager starts threads, CodexThread.submit(Op::UserInput) sends turns, and CodexThread.next_event() emits typed Codex events
• the current adapter uses that runtime surface directly from Rust, then bridges a narrow event/tool API to Swift
• iOS builds require a small upstream patch that removes codex-code-mode's V8 dependency from iOS targets
• the mobile runtime profile must keep shell/process tools, PTYs, subprocess MCP, and desktop sandbox helpers unreachable

Requirements

• Swift 5.10+
• iOS 17+
• macOS 14+
• OpenAI API key for live agent calls

Use The Package

import CodexKit

let registry = CodexToolRegistry()
await registry.register(CodexTool(
    name: "searchNotes",
    description: "Search notes by title or tag.",
    inputSchema: [
        "type": "object",
        "properties": [
            "query": ["type": "string"],
        ],
        "required": ["query"],
        "additionalProperties": false,
    ]
) { arguments in
    #"{"results":[]}"#
})

let client = CodexClient(
    auth: .apiKey(apiKey),
    configuration: CodexClientConfiguration(model: "gpt-5.4"),
    tools: registry
)
let thread = try await client.prewarmThread()

for try await event in await thread.send("Find my launch notes") {
    switch event {
    case .assistantTextDelta(let text):
        print(text, terminator: "")
    case .toolCallStarted(let call):
        print("Running \(call.name)")
    default:
        break
    }
}

prewarmThread() builds the native Codex runtime and starts an upstream Codex thread before the first visible send. Apps can call it after auth is available, then keep the returned CodexThread for the first user action.

CodexKit also exposes Codex's bundled picker-safe API model catalog:

let models = CodexModel.bundledSupported

Field Notes Sample

Build the local Rust FFI artifact first:

./scripts/build-local-ffi-xcframework.sh

Run in Xcode / iOS Simulator:

cd Examples/FieldNotesSample
xcodegen generate
open FieldNotesSample.xcodeproj

Choose the FieldNotesSample-iOS scheme. The Xcode project is important: opening the sample Package.swift directly gives Xcode a raw SwiftPM executable target, not a proper iOS .app bundle.

To run on a physical device, copy the local signing template and put your Apple team and bundle prefix in the ignored file:

cd Examples/FieldNotesSample
cp Local.xcconfig.example Local.xcconfig

Local.xcconfig is intentionally git-ignored. The generated app bundle ID is $(CODEXKIT_SAMPLE_BUNDLE_ID_PREFIX).FieldNotesSample.

Run on macOS from SwiftPM:

cd Examples/FieldNotesSample
OPENAI_API_KEY=sk-... swift run FieldNotesSample

The sample is intentionally app-shaped rather than a blank chat demo. It starts with seeded notes, model selection, shortcut prompts, visible tool calls, and a floating agent tray so the agent can demonstrate tool calls against app state.

Development

./scripts/build-local-ffi-xcframework.sh
swift test

Check the real Codex runtime iOS build from SwiftPM:

cd Examples/FieldNotesSample
swift build

Check only the Rust adapter for device iOS:

cd Upstream/codex/codex-rs
IPHONEOS_DEPLOYMENT_TARGET=17.0 cargo +1.91.1 check -p codexkit-ffi --target aarch64-apple-ios

Refresh upstream Codex when needed:

git submodule update --remote Upstream/codex

App Store Safety

CodexKit v1 avoids host-computer agent capabilities:

• no shell execution
• no PTY
• no process spawning
• no hidden filesystem traversal
• no downloaded executable code
• no subprocess MCP servers

Host apps explicitly register the tools they want the agent to use.