> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chappiesdk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chappie SDK: Native ChatGPT Assistant for iOS & macOS

> Chappie is a Swift SDK that embeds a ChatGPT-powered assistant into your iOS or macOS app using device-code auth — no Platform API key required.

Chappie is a Swift SDK that lets you add a native, harness-first ChatGPT assistant directly into your iOS or macOS app. Rather than proxying through a backend you maintain or exposing a raw OpenAI Platform API key in your client, Chappie authenticates the user with their own ChatGPT account through a standard OAuth device-code flow, stores credentials securely in the system Keychain, and then drives conversations through the ChatGPT/Codex backend on the user's behalf.

## 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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication/overview">
    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.
  </Card>

  <Card title="Harnesses" icon="layer-group" href="/concepts/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.
  </Card>

  <Card title="Streaming" icon="bolt" href="/concepts/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.
  </Card>

  <Card title="Host Tools" icon="wrench">
    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.
  </Card>

  <Card title="Context Management" icon="brain">
    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.
  </Card>

  <Card title="Runtime Thread Store" icon="database">
    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.
  </Card>
</CardGroup>

## How Chappie Works

When a user opens your app for the first time, Chappie presents `ChappieSignIn` — 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.

<Note>
  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.
</Note>

## 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** use `api.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.

<Tip>
  For multi-account apps or shared Keychain setups, pass a `ChappieConfiguration` with a distinct `keychainAccount` per user ID when creating both the auth session and the client. This keeps each user's credentials cleanly isolated in the Keychain.
</Tip>