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