Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -32,3 +32,19 @@ jobs:
cache-dependency-path: examples/auth0/package-lock.json
- run: npm ci --prefix examples/auth0
- run: npm test --prefix examples/auth0


mobile-template:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
cache-dependency-path: apps/mobile/package-lock.json
- run: npm ci --prefix apps/mobile
- run: npm run test --prefix apps/mobile
- run: npm run typecheck --prefix apps/mobile
- run: npm run bundle:ios --prefix apps/mobile
- run: npm run bundle:android --prefix apps/mobile
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,4 @@ dist/
.next/
next-env.d.ts
assets/fonts/
apps/mobile/.expo/
16 changes: 13 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Your project and its core functionality must be created during the event. Existi

## Templates

These starting points serve different kinds of context. **CopilotKit Channels** brings the Slack agent into the conversation; **CopilotKit React** connects the web agent to the app people are using.
These starting points serve different kinds of context. **CopilotKit Channels** brings the Slack agent into the conversation; **CopilotKit React** connects the web agent to the app people are using; **CopilotKit React Native** brings the same agent pattern onto a phone.

### 1. Slack — an agent that joins the thread

Expand All @@ -63,13 +63,23 @@ The included web app supplies page context, frontend tools, and agent-rendered U

**[Use the web template →](templates/web.md)** · [CopilotKit docs](https://docs.copilotkit.ai/) · [Ambiguous AI setup](using-sponsor-tools.md#ambiguous-ai)

### 3. React Native — an agent in your pocket

**OpenAI or OpenRouter + CopilotKit React Native**

A mobile agent reads app state, renders native cards, and waits for a tap before changing local sample data. Start with a personal finance assistant, a field checklist, an inventory counter, or any workflow where phone context and approval matter.

The included Expo app supplies seeded finance state, native rendered tool UI, a human-in-the-loop expense approval, and a mobile-specific CopilotKit runtime endpoint served by the web app. Configure your model provider, start `npm run dev:web`, then run the mobile app from `apps/mobile`.

**[Use the React Native template →](templates/react-native.md)** · [Mobile app README](apps/mobile/README.md)

### The demo you can build on

The supplied on-call assistant is an **infrastructure example**: read ambient context, call a tool, render useful UI, and return a verifiable result. **Branch out from the example app.** Choose a different user, problem, dataset, and interaction; the goal is your own project, not another version of the incident demo.

Use the [demo prompts](dev-docs/demo-prompts.md) to learn how the pieces connect, then replace the incident scenario. Approval cards in the Slack/web reference demo record decisions; they do not execute production actions or enforce authorization around every external tool.

Want another surface? The kit also includes [voice, MCP, mobile, and terminal starting points](dev-docs/surfaces.md). Four event surfaces are inspiration, not separate tracks or a requirement to build four apps.
Want another surface? The kit also includes [voice, MCP, and terminal starting points](dev-docs/surfaces.md). The event surfaces are inspiration, not separate tracks or a requirement to build multiple apps.

## Coding agent

Expand Down Expand Up @@ -101,4 +111,4 @@ The [template guides](templates/) provide launch commands, files to customize, a
| Rehearse and debug | [Demo prompts](dev-docs/demo-prompts.md) · [Troubleshooting](dev-docs/troubleshooting.md) |
| Prepare your entry | [Submission checklist](SUBMISSION.md) |

For the Slack/web workspaces, `npm run verify` runs typechecks, tests, and MCP checks without credentials. `npm run check-env` validates configured startup. Live sponsor calls and platform delivery require your accounts. See [developer docs](dev-docs/README.md) for detailed setup and deployment.
For the Slack/web workspaces, `npm run verify` runs typechecks, tests, and MCP checks without credentials. The mobile app has its own install, tests, typecheck, and Metro export checks under `apps/mobile`. `npm run check-env` validates configured startup. Live sponsor calls and platform delivery require your accounts. See [developer docs](dev-docs/README.md) for detailed setup and deployment.
1 change: 1 addition & 0 deletions apps/mobile/.env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
EXPO_PUBLIC_RUNTIME_URL=http://localhost:3100/api/mobile-copilotkit
158 changes: 100 additions & 58 deletions apps/mobile/README.md
Original file line number Diff line number Diff line change
@@ -1,75 +1,117 @@
# apps/mobile — in your pocket
# apps/mobile — React Native template

An Expo app on the same agent. **Deliberately not an npm workspace member**: React
Native pins its own `react` and `react-native`, and hoisting those into the root
workspace can break `apps/web`. It installs and runs on its own.
An Expo app for Template 3: a mobile finance copilot that reads app state, renders native cards in chat, and waits for a tap before changing local sample data.

## Status — read this first
The app is deliberately not an npm workspace member. React Native pins its own `react`, `react-native`, and Expo versions, and hoisting those into the root workspace can break the web app.

| | |
|---|---|
| Installs, resolves, typechecks | **verified** |
| Import surface, polyfill order, headless API | **verified against 1.70.1** |
| Actually running on a simulator or device | **not verified — you do this** |
## Status

The other three surfaces in this kit were exercised end to end. This one was not,
because it needs a simulator build. Everything below is the config that *should*
be right; budget ten minutes to prove it before you build a demo on it.
| Check | Status |
| --- | --- |
| Dependency install | verified with `npm ci --prefix apps/mobile` |
| Offline tests | verified with `npm test --prefix apps/mobile` for the mobile regression suite |
| TypeScript | verified with `npm run typecheck --prefix apps/mobile` |
| Metro exports | verified for iOS and Android with `npm run bundle:ios --prefix apps/mobile` and `npm run bundle:android --prefix apps/mobile` |
| iOS Expo Go smoke | verified clean Expo Go startup in the iOS Simulator |
| Live OpenAI chat | verified on iOS Simulator with Expo Go and `gpt-5.6-sol` for balances, formatted Markdown/link output, an approved expense, and a canceled expense |
| Approval UI end-to-end | verified on iOS Simulator: the $9 Souvla proposal left Rewards Card at -$612.40 until **Add expense**, then changed it to -$621.40; canceling a $5 coffee at Blue Bottle left -$621.40 unchanged |
| OpenRouter live run / physical phone / OCR verification | not claimed in this PR |

## Run it

Start the runtime first from the repository root:

```bash
cd apps/mobile
npm install
npm start # then press i for iOS, a for Android
npm run dev:web
```

The runtime uses the root model configuration. OpenAI and OpenRouter both work through the shared model resolver:

```dotenv
MODEL_PROVIDER=openai
OPENAI_API_KEY=your-key
MODEL=gpt-5.6-sol
```

```dotenv
MODEL_PROVIDER=openrouter
OPENROUTER_API_KEY=your-key
MODEL=openai/gpt-5.6-sol
```

The runtime it talks to is `apps/web` — start that first:
Then run the mobile app:

```bash
npm run dev --workspace web # from the repo root, serves :3100
cd apps/mobile
npm ci
npm run typecheck
npm run bundle:ios
npm run bundle:android
npm start
```

## The one thing that will bite you
Press `i` for the iOS Simulator or `a` for Android. For a physical device, first make the web runtime reachable from the device, then scan the Expo code.

`localhost` on a phone means **the phone**.
## Runtime URL

The default endpoint is `http://localhost:3100/api/mobile-copilotkit`, served by `apps/web`. On a real phone, `localhost` means the phone, not your laptop.

| Target | `EXPO_PUBLIC_RUNTIME_URL` |
|---|---|
| iOS Simulator | `http://localhost:3100/api/copilotkit` (the default) |
| Android emulator | `http://10.0.2.2:3100/api/copilotkit` |
| Physical device | `http://<your-laptop-LAN-IP>:3100/api/copilotkit` |

Put it in `apps/mobile/.env`.

## Why the imports look like that

- **`@copilotkit/react-native/headless`, never the root barrel.** The root entry
imports `expo-document-picker` and `expo-file-system` unconditionally; the
headless subpath imports none of the optional native peers. Verified by reading
the published 1.70.1 bundles.
- **`index.js` import order is load-bearing.** `react-native-get-random-values`
first (otherwise CopilotKit installs a `Math.random()` crypto shim and warns
that it is not secure), then `@copilotkit/react-native/polyfills`, then the
app. The barrel overrides `global.fetch`, and importing it before React
Native's `InitializeCore` gets that override clobbered.
- **One polyfill import is enough on 1.70.1.** The barrel now installs streams,
encoding, crypto, DOMException and location plus streaming fetch. Older
versions only did streaming-fetch and needed all five granular subpaths.
- **Tool calls render through `useRenderToolCall()`.** It resolves the renderer
*and* supplies `respond`, which is what makes the approval card answerable.
Walking the render registry by hand is a trap — the local `useRenderTool`
registry passes only `{ args, status }` with no `respond`, so approvals look
fine and silently cannot be answered.

## If Metro complains

Two things this kit does not need but you might, if you start importing the root
barrel or hit a transitive Node-only dependency:

- **Stub optional native modules** in `metro.config.js` via `resolveRequest`.
- **`jose`** (a transitive JWT dependency) resolves to its Node build. Add the
`browser` export condition for `jose` **only** — adding it to
`unstable_conditionNames` globally breaks React Native core.
- **zod 4** uses `export * as ns from`, which needs
`@babel/plugin-transform-export-namespace-from` on older Babel setups.
| --- | --- |
| iOS Simulator | `http://localhost:3100/api/mobile-copilotkit` |
| Android emulator | `http://10.0.2.2:3100/api/mobile-copilotkit` |
| Physical device | `http://<your-laptop-LAN-IP>:3100/api/mobile-copilotkit` using the LAN URL printed by `npm run dev:web`, or after deploying the runtime |

Put the override in `apps/mobile/.env`. Current main runs Next.js without a forced host binding. For a physical device, use the LAN URL printed by `npm run dev:web`, or deploy the runtime first.

## What to try

The [React Native walkthrough](../../dev-docs/template-walkthroughs/mobile/README.md) shows the verified iOS Simulator evidence for startup, balances, approval, cancellation, and formatted assistant output.

Ask:

```text
Show my balances.
```

Expected: `list_mobile_accounts` renders a native account card.

Ask:

```text
How am I doing on budgets?
```

Expected: `list_mobile_budgets` renders spent/limit rows.

Ask:

```text
Add a $9 lunch at Souvla to my Rewards Card.
```

Expected: `add_mobile_expense` renders an approval card. Tapping **Add expense** updates the local in-memory account balance and returns a local transaction ID. Tapping **Cancel** changes nothing.

## How it is wired

| Piece | File |
| --- | --- |
| App shell | [App.tsx](App.tsx) |
| Headless chat | [src/chat.tsx](src/chat.tsx) |
| Finance sample state | [src/finance.ts](src/finance.ts) |
| CopilotKit tools and app context | [src/tools.tsx](src/tools.tsx) |
| Runtime URL | [src/config.ts](src/config.ts) |
| Mobile runtime endpoint | [../web/src/app/api/mobile-copilotkit/[[...path]]/route.ts](../web/src/app/api/mobile-copilotkit/[[...path]]/route.ts) |
| Mobile prompt | [../../packages/agent-core/src/mobile-finance-prompt.ts](../../packages/agent-core/src/mobile-finance-prompt.ts) |

Imports come from `@copilotkit/react-native/headless` so the template avoids optional native peers from the prebuilt chat UI. `index.js` imports `react-native-get-random-values` before CopilotKit polyfills, then registers the Expo app.

`metro.config.js` routes the transitive `jose` dependency through its browser export for native bundles. This is intentionally narrow: it does not stub Node built-ins or mask missing native functionality.

## Limits

This template changes local sample state only. It does not connect to bank accounts, cards, payment services, external storage, messaging providers, or the OpenAI Realtime voice route. Use it as the phone-native approval and app-context pattern, then replace the sample finance data and tools with your hackathon workflow.

## Upstream source

Inspired by CopilotKit PR [#5430](https://github.com/CopilotKit/CopilotKit/pull/5430), `examples/showcases/react-native-personal-finance` at commit `6815a3eed0d80570cc17c121d952b94d5543d0a7`. This app adapts the concept into the starter kit's existing Expo app and shared web runtime. It does not copy the standalone bare native project, screenshots, video, Git LFS media, or credentials.
25 changes: 25 additions & 0 deletions apps/mobile/metro.config.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
const { getDefaultConfig } = require("expo/metro-config");

const config = getDefaultConfig(__dirname);
const defaultResolveRequest = config.resolver.resolveRequest;

config.resolver.resolveRequest = (context, moduleName, platform) => {
if (moduleName === "jose" || moduleName.startsWith("jose/")) {
return context.resolveRequest(
{
...context,
unstable_conditionNames: ["browser", "require", "import"],
},
moduleName,
platform,
);
}

if (defaultResolveRequest) {
return defaultResolveRequest(context, moduleName, platform);
}

return context.resolveRequest(context, moduleName, platform);
};

module.exports = config;
Loading
Loading