Codex surfaces and AGENTS.md for a mobile repo

Where each surface runs your code

Here's the mobile-specific catch. A cloud task can write code, install dependencies and run the type checker and unit tests in its own environment, but it can't tap through your app on the iOS Simulator sitting on your Mac. So route by what the task needs to see. Anything you judge by looking at a screen belongs on your machine. Refactors, tests, migrations and docs can run in a worktree or in the cloud.

Worktrees: parallel chats without collisions

A Git worktree is a second checkout of your repository that shares the same .git history. In the ChatGPT desktop app you pick Worktree under the composer and choose a starting branch; Codex creates the worktree and works there, in a detached HEAD state by default. When you're ready you either click Create branch here and keep going in the worktree, or use Handoff to move the chat and its code into your Local checkout. In the CLI, codex --worktree starts a session in a new managed worktree and /worktree moves the current conversation into one.

Mobile adds two wrinkles. Each worktree needs its own node_modules, so the first install takes time. And only one copy of your app, with one bundle identifier, runs on a simulator at a time. OpenAI's docs list “you can run only one instance of your app” as a reason to hand a chat back to Local before testing. If two worktrees each need a dev server, start the second one on another port, for example npx expo start --port 8082.

Cloud tasks from your terminal

Codex Cloud runs each task in its own workspace inside an environment you've prepared once: repositories, dependencies, network access and secrets. You can start and inspect cloud tasks without leaving the CLI. codex cloud opens a picker, codex cloud exec --env <ENV_ID> "…" submits a task directly (add --attempts 3 for best-of-N), codex cloud list shows recent tasks, codex cloud diff <TASK_ID> prints the result, and codex cloud apply <TASK_ID> applies it to your local checkout so you can run it on the simulator.

Your phone as the remote control

The ChatGPT iOS app can drive Codex on Cloud or on a connected Mac or PC. You set it up from the desktop app (Settings › Connections › Control this Mac or PC), scan a QR code with your phone, and keep the computer awake and online. From the phone you can start tasks, follow progress, approve requested commands and review changed files. The repository and any worktrees stay on the computer; nothing runs on the phone itself.

AGENTS.md: the briefing every surface reads

AGENTS.md is a plain Markdown file of instructions for coding agents, stewarded by the Agentic AI Foundation and read by Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent and many others. Claude Code reads it too when a project has no CLAUDE.md. Codex reads AGENTS.md before doing any work, in every surface, so it's the cheapest place to put the rules a new teammate would need on day one.

1. Global: ~/.codex/AGENTS.override.md if it exists, otherwise ~/.codex/AGENTS.md.
2. Project: from the repository root down to your current directory, at most one file per folder: AGENTS.override.md first, then AGENTS.md, then any fallback names you configure.
3. Merge: files are joined from the root down, so instructions closer to where you're working come later and win when they conflict.
4. Limit: Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. It rebuilds the chain at the start of each session.

Run /init in a new repo and Codex drafts a scaffold for you to edit. Then cut it down. Everything in AGENTS.md is read on every turn of every session, so a bloated file costs tokens, crowds out the files Codex actually needs, and can be truncated at the cap. Put commands, conventions and hard rules in it. Put long procedures in skills, which Codex loads only when a task needs them.

# AGENTS.md
Expo SDK 58 app, TypeScript strict, routes in src/app.

# Tipjar
Expo SDK 58 app. TypeScript strict. Routes in src/app, shared code in src/lib.

## Commands
- Dev server: npx expo start
- Before saying "done": npx tsc --noEmit && npm test
- Native rebuild after native changes: npx expo run:ios

## Rules
- Add packages with npx expo install <pkg>.
- Never hand-edit ios/ or android/; use app.json and config plugins.
- Only EXPO_PUBLIC_ variables in app code. No secret keys in the app.
- Tell me what to check on the simulator when a change is visual.