Codex Expo Run Actions

Codex Run Actions for Expo

Use this skill to connect an Expo project to the Codex app action bar.

The goal is one project-local script plus .codex/environments/environment.toml, so the user can press Run in the Codex app and see the Expo CLI / Metro logs in an action terminal.

Workflow

1. Confirm the current workspace is an Expo app.

   • Look for package.json.

   • Look for app.json, app.config.js, app.config.ts, or expo in package.json.

   • Do not wire the Codex action at a monorepo root if the Expo app is in a child package.

2. Discover the package runner.

   • Prefer the package manager declared in packageManager.

   • Otherwise infer from lockfiles.

   • The generated run script should still have a safe fallback to npx expo.

3. Create or update script/build_and_run.sh.

   • Use the reference file for the script shape.

   • Default no-argument mode starts the Expo dev server: expo start.

   • Keep the dev server in the foreground so the Codex action terminal owns logs and Ctrl-C behavior.

   • Support optional modes for direct buttons:

     • --ios starts Expo and opens iOS simulator.

     • --android starts Expo and opens Android.

     • --web starts Expo for web.

     • --dev-client starts in dev-client mode.

     • --tunnel starts a tunnel.

     • --export-web exports web.

4. Write .codex/environments/environment.toml.

   • Always add or update one primary action named Run.

   • Wire Run to ./script/build_and_run.sh.

   • Add direct Run iOS, Run Android, Run Web, or Run Dev Client actions only when the user asks for those buttons or the project clearly needs them.

   • If the environment file already exists, update the existing matching action instead of duplicating it.

5. Use the action script as the default local run path.

   • After wiring, run ./script/build_and_run.sh --help or a short non-server mode if you need to sanity-check syntax.

   • Do not start a long-lived Metro server during a setup-only task unless the user asked you to run the app.

References

• references/expo-run-button-bootstrap.md: canonical Expo script/build_and_run.sh and Codex environment action examples.

Guardrails

• Try Expo Go / expo start first; do not default the Codex Run button to expo run:ios, expo run:android, prebuild, or EAS Build.

• Do not wire cloud actions such as eas build, eas submit, or store deployment into Codex buttons unless the user explicitly asks and accepts the auth / time / cost tradeoff.

• Do not create a nested git repo.

• Do not put secrets in .codex/environments/environment.toml or in the run script.

• Do not background Metro from the run script; the action terminal should show the active server logs.

• Do not hard-code npm if the project uses pnpm, yarn, or bun.

Output Expectations

When setup changes are made, summarize:

• the Expo app root you wired

• the run script path

• the Codex environment file path

• the actions added or updated

• how to launch the same path from shell