build-and-run-macos-app — Codex command: what it does, how to install
Generates or updates the build_and_run.sh script and connects the Run button in the Codex app. Built for macOS targets using Xcode or SwiftPM.
~/.codex/prompts/build-and-run-macos-app.mdWhat build-and-run-macos-app does
The command inspects the project structure to detect an Xcode workspace, an Xcode project, or a SwiftPM package. If the repository lacks git tracking, it runs git init at the project root. Nested git initialization is blocked.
Its main job is maintaining script/build_and_run.sh. The generated script stops any running instance, builds the target, and runs the fresh binary. For AppKit or SwiftUI GUI applications built with SwiftPM, the script packages a local .app bundle and starts it via /usr/bin/open -n. Command-line tools run directly.
The script follows the contract required for .codex/environments/environment.toml. Optional flags include --debug, --logs, --telemetry, and --verify. These modes run only when requested. Any build or launch errors produce a concise summary.
What it helps with
- Wire the Codex app Run button to build macOS targets
- Create a build-and-relaunch script for Xcode and SwiftPM projects
- Bundle SwiftPM SwiftUI applications into local
.apppackages - Add debug and log-checking modes to
script/build_and_run.sh
Example prompts for the agent
- /build-and-run-macos-app mode:run
- /build-and-run-macos-app project:MyApp.xcodeproj scheme:MyApp mode:debug
- /build-and-run-macos-app product:MyCLI mode:logs
How to install build-and-run-macos-app
Manually: put the files in place
~/.codex/prompts/build-and-run-macos-app.mdCall it with /prompts:build-and-run-macos-app. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.claude/commands/build-and-run-macos-app.mdCall it with /build-and-run-macos-app. For all projects use ~/.claude/commands/
Manually: put the files in place
.github/prompts/build-and-run-macos-app.prompt.mdManually: put the files in place
.gemini/commands/build-and-run-macos-app.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about build-and-run-macos-app
How to install build-and-run-macos-app in Codex?
Save the file to ~/.codex/prompts/build-and-run-macos-app.md. Once saved, the command is ready to use in Codex.
What does the build-and-run-macos-app command do?
It detects your project layout, writes script/build_and_run.sh, and updates .codex/environments/environment.toml. The script kills previous instances, triggers a fresh build, and runs the application.
How does it handle SwiftPM graphical applications?
Standalone CLI tools run directly from their executable path. For AppKit or SwiftUI GUI applications, the script creates a project-local .app bundle and starts it through /usr/bin/open -n.
Source text
build-and-run-macos-app.md · MIT
# /build-and-run-macos-app Create or update the project-local macOS `build_and_run.sh` script, wire the Codex app Run button, then use that script as the default build/run entrypoint. ## Arguments - `scheme`: Xcode scheme name (optional) - `workspace`: path to `.xcworkspace` (optional) - `project`: path to `.xcodeproj` (optional) - `product`: SwiftPM executable product name (optional) - `mode`: `run`, `debug`, `logs`, `telemetry`, or `verify` (optional, default: `run`) - `app_name`: process/app name to stop before relaunching (optional) ## Workflow 1. Detect whether the repo uses an Xcode workspace, Xcode project, or SwiftPM package. 2. If the workspace is not inside git yet, run `git init` at the project root so Codex app git-backed features unlock. 3. Create or update `script/build_and_run.sh` so it always stops the current app, builds the macOS target, and launches the fresh result. 4. For SwiftPM, keep raw executable launch only for true CLI tools; for AppKit/SwiftUI GUI apps, create a project-local `.app` bundle and launch it with `/usr/bin/open -n`. 5. Support optional script flags for `--debug`, `--logs`, `--telemetry`, and `--verify`. 6. Follow the canonical bootstrap contract in `../skills/build-run-debug/references/run-button-bootstrap.md` for the exact script shape and `.codex/environments/environment.toml` format. 7. Run the script in the requested mode and summarize any build, script, or launch failure. ## Guardrails - Do not initialize a nested git repo inside an existing parent checkout. - Do not leave stale `Run` actions pointing at old script paths. - Keep the no-flag script path simple: kill, build, run. - Use `--debug`, `--logs`, `--telemetry`, or `--verify` only when the user asks for those modes.
© OpenAI · MIT · openai/plugins
