Codex Expo Run Actions

OpenAIOfficialCreated by Expo TeamDistributed by OpenAI

Skill
Workflow
Automation and integrations
MIT
No issues found

From the author

Wire Expo projects into the Codex app with project-local run scripts and .codex/environments/environment.toml actions. Use when the user wants the Codex app Run button, build/run actions, action buttons, or a stable Expo start/run workflow from Codex.

— the description by Expo Team

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill automates the configuration required to run Expo projects directly from the Codex app interface. It establishes a standardized project-local execution script and updates the .codex/environments/environment.toml file, enabling the Codex Run button to trigger Expo development servers. The process ensures that logs are captured within the Codex action terminal and respects the project's existing package manager configuration.

What it does

Identifies Expo project roots and detects the appropriate package manager.
Creates a standardized build_and_run.sh script for consistent execution.
Configures the .codex/environments/environment.toml file to enable the Run button.
Supports optional platform-specific run modes like iOS, Android, and Web.
Ensures the Expo dev server runs in the foreground for proper log visibility.
Updates existing environment configurations without duplicating actions.

When to use it

When you want to launch your Expo project directly from the Codex app.
When you need a stable, repeatable way to start your Expo dev server.
When you want to see Expo CLI and Metro logs directly inside the Codex action terminal.
When you need to add platform-specific run buttons to your Codex environment.

Advantages

Provides a consistent, one-click development workflow.
Maintains project-local control over execution scripts.
Integrates seamlessly with existing package manager setups like pnpm, yarn, or bun.
Keeps development logs accessible within the IDE environment.

Usage examples

“Wire my Expo project to the Codex Run button.”: The agent creates the script/build_and_run.sh file and updates the .codex/environments/environment.toml to include a primary Run action.
“Add a Run iOS button to my Codex environment.”: The agent updates the .codex/environments/environment.toml to include a new action button that executes the run script with the --ios flag.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/openai/codex-expo-run-actions/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip codex-expo-run-actions.zip -d .agents/skills

Documentation by Expo Team

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

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

Files

ATTRIBUTION.mdAdded by AutoGineer834 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md3.3 KiB
agents/openai.yaml394 B
references/expo-run-button-bootstrap.md4.9 KiB

references/expo-run-button-bootstrap.md

Expo Run Button Bootstrap

This is the canonical bootstrap contract for connecting an Expo app to the Codex app action bar.

When an Expo project does not already have a Codex run entrypoint:

Create one project-local script/build_and_run.sh.
Make it executable.
Keep the default path as the fastest low-risk local run loop: expo start.
Write .codex/environments/environment.toml so the Codex app exposes a Run action wired to that script.
Add more action buttons only when they match the project and the user's ask.

`script/build_and_run.sh`

Use this shape as the default Expo run script. Keep the dev server in the foreground: the Codex action terminal owns the running process and shows Metro / Expo CLI logs.

#!/usr/bin/env bash
set -euo pipefail

MODE="${1:-start}"
ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"

cd "$ROOT_DIR"

show_usage() {
  cat <<'USAGE'
usage: ./script/build_and_run.sh [mode]

Modes:
  start, run        Start the Expo dev server
  --ios, ios        Start Expo and open iOS
  --android, android
                   Start Expo and open Android
  --web, web        Start Expo for web
  --dev-client, dev-client
                   Start Expo in development-client mode
  --tunnel, tunnel Start Expo using tunnel transport
  --export-web, export-web
                   Export the web build locally
  --doctor, doctor Run Expo diagnostics
  --help, help     Show this help
USAGE
}

resolve_expo_cmd() {
  if [[ -n "${EXPO_CLI:-}" ]]; then
    # Optional escape hatch for projects that need a wrapper command.
    # shellcheck disable=SC2206
    EXPO_CMD=(${EXPO_CLI})
    return
  fi

  if [[ -f pnpm-lock.yaml ]] && command -v pnpm >/dev/null 2>&1; then
    EXPO_CMD=(pnpm exec expo)
  elif [[ -f yarn.lock ]] && command -v yarn >/dev/null 2>&1; then
    EXPO_CMD=(yarn expo)
  elif { [[ -f bun.lock ]] || [[ -f bun.lockb ]]; } && command -v bun >/dev/null 2>&1; then
    EXPO_CMD=(bunx expo)
  else
    EXPO_CMD=(npx expo)
  fi
}

run_doctor() {
  if [[ -f pnpm-lock.yaml ]] && command -v pnpm >/dev/null 2>&1; then
    pnpm exec expo-doctor
  elif [[ -f yarn.lock ]] && command -v yarn >/dev/null 2>&1; then
    yarn expo-doctor
  elif { [[ -f bun.lock ]] || [[ -f bun.lockb ]]; } && command -v bun >/dev/null 2>&1; then
    bunx expo-doctor
  else
    npx expo-doctor
  fi
}

resolve_expo_cmd

case "$MODE" in
  start|run)
    exec "${EXPO_CMD[@]}" start
    ;;
  --ios|ios)
    exec "${EXPO_CMD[@]}" start --ios
    ;;
  --android|android)
    exec "${EXPO_CMD[@]}" start --android
    ;;
  --web|web)
    exec "${EXPO_CMD[@]}" start --web
    ;;
  --dev-client|dev-client)
    exec "${EXPO_CMD[@]}" start --dev-client
    ;;
  --tunnel|tunnel)
    exec "${EXPO_CMD[@]}" start --tunnel
    ;;
  --export-web|export-web)
    exec "${EXPO_CMD[@]}" export --platform web
    ;;
  --doctor|doctor)
    run_doctor
    ;;
  --help|help)
    show_usage
    ;;
  *)
    show_usage >&2
    exit 2
    ;;
esac

Primary Codex environment

Write the environment file at this exact path:

.codex/environments/environment.toml

Use one primary Run action by default:

# THIS IS AUTOGENERATED. DO NOT EDIT MANUALLY
version = 1
name = "<project-name>"

[setup]
script = ""

[[actions]]
name = "Run"
icon = "run"
command = "./script/build_and_run.sh"

If the project already has an environment file, update the existing Run action's command instead of adding a second Run action.

Optional action buttons

Add these only when useful for the project and the user has asked for direct buttons. Keep the primary Run button even if you add platform-specific buttons.

[[actions]]
name = "Run iOS"
icon = "run"
command = "./script/build_and_run.sh --ios"

[[actions]]
name = "Run Android"
icon = "run"
command = "./script/build_and_run.sh --android"

[[actions]]
name = "Run Web"
icon = "run"
command = "./script/build_and_run.sh --web"

[[actions]]
name = "Run Dev Client"
icon = "run"
command = "./script/build_and_run.sh --dev-client"

[[actions]]
name = "Expo Doctor"
icon = "tool"
command = "./script/build_and_run.sh --doctor"

Build actions

Prefer a safe local export/check action over cloud or store operations:

[[actions]]
name = "Export Web"
icon = "tool"
command = "./script/build_and_run.sh --export-web"

Only wire native or cloud builds when the user explicitly asks:

expo run:ios / expo run:android can generate or require native project state.
eas build is remote, authenticated, and can take a long time.
eas submit and store workflows can publish to external stores.

Testing the wiring

For setup-only changes, test syntax without starting a long-lived server:

bash -n ./script/build_and_run.sh
./script/build_and_run.sh --help

When the user asks you to run the app, use:

./script/build_and_run.sh

The server should stay in the foreground until the action terminal or shell stops it.

Requirements and compatibility

Written for: OpenAI Codex

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Expo Team

Publisher

OpenAI (Official)

Distributed by

OpenAI

Source

openai/plugins · plugins/expo/skills/codex-expo-run-actions · commit d420d13

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from plugins/expo/LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Expo Team or OpenAI.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download codex-expo-run-actions.zip