Requirements
Before you integrate Chappie, make sure your project meets these minimum requirements:| Requirement | Minimum version |
|---|---|
| Swift | 6.0 |
| iOS | 16.0 |
| macOS | 13.0 |
| Xcode | Latest stable release with iOS Simulator support |
SDK Products
Chappie ships as three separate Swift package products so you only link what your app needs:| Product | Link to | Purpose |
|---|---|---|
ChappieSDK | App targets | Authentication, client, harnesses, streaming, and host tools. Required for all apps. |
ChappieSDKRuntime | App targets (optional) | Durable thread storage via ChappieFileThreadStore and normalized runtime turn events. Add only when you need transcripts to survive app launches. |
ChappieSDKTesting | Test targets only | Seeded auth fixtures for unit and UI tests. Never link this to an app target. |
Key Features
Authentication
Sign users in via ChatGPT’s OAuth device-code flow. Credentials are stored in the system Keychain under configurable service, account, and access-group keys. The public API never exposes raw token fields — your app receives auth state and account metadata only.
Harnesses
A
ChappieHarness places your app’s context, capabilities, and custom tools as the first item in every transcript. Declare what your app can do so the model always has the right framing before the user’s first message arrives.Streaming
Stream responses token-by-token over a WebSocket connection with automatic reconnection and five retries before gracefully falling back to HTTP/SSE. Replay divergence is detected and surfaced as an error rather than silently corrupting UI output.
Host Tools
Register
ChappieHostTool handlers on the client so the model can invoke Swift functions in your app — look up records, read app state, or call local APIs — and weave the results back into the conversation automatically.Context Management
Snapshot, clear, resume, and compact the active transcript through the
ChappieClient context API. Use compactContext(summary:) to summarize long threads before they reach the model’s context window, or call compactContext() to let Chappie generate the summary.Runtime Thread Store
The optional
ChappieSDKRuntime product adds durable transcript storage through ChappieFileThreadStore. Threads survive app launches, are excluded from backups by default, and benefit from NSFileProtectionComplete on iOS. A configurable retention policy archives inactive threads after 30 days and deletes archived threads after a further 60 days within a 256 MiB total cap.How Chappie Works
When a user opens your app for the first time, Chappie presentsChappieSignIn — a SwiftUI button that launches the ChatGPT device-code onboarding sheet. The user approves the link on chatgpt.com, and Chappie stores the resulting credentials in the Keychain. After that, your app creates a ChappieClient with a ChappieHarness that describes the app’s context and capabilities. Every call to client.send(_:) or client.stream(_:) prepends the harness manifest to the transcript so the model always understands which app surface it is talking through. Credentials refresh automatically before requests, and a 401 triggers one automatic re-authentication cycle before the error surfaces.
Chappie automatically schedules a local notification — “ChatGPT Linked! Return to the app” — when the device-code flow completes, provided the user has granted notification permission.
What Chappie Is Not
Chappie uses the ChatGPT/Codex backend and the user’s own ChatGPT account. It is not a third-party proxy that forwards requests through a server you operate, and it does not useapi.openai.com Platform API keys. Your app never touches a raw API key. If your use case requires direct Platform API access with your own key, Chappie is not the right tool for that workflow.