Build Run Debug

Build / Run / Debug

Quick Start

Use this skill to set up one project-local script/build_and_run.sh entrypoint, wire .codex/environments/environment.toml so the Codex app shows a Run button, then use that script as the default build/run path.

Prefer shell-first workflows:

• ./script/build_and_run.sh as the single kill + build + run entrypoint once it exists
• xcodebuild for Xcode workspaces or projects
• swift build plus raw executable launch inside that script for true SwiftPM command-line tools
• swift build plus project-local .app bundle staging and /usr/bin/open -n launch for SwiftPM AppKit/SwiftUI GUI apps
• optional script flags for lldb, log stream, telemetry verification, or post-launch process checks

Do not assume simulators, touch interaction, or mobile-specific tooling.

If an Xcode-aware MCP surface is already available and the user explicitly wants it, use it only where it fits. Keep that usage narrow and honest: prefer it for Xcode-oriented discovery, logging, or debugging support, and do not force simulator-specific workflows onto pure macOS tasks.

Workflow

1. Discover the project shape.

• Check whether the workspace is already inside a git repo with git rev-parse --is-inside-work-tree.
• If no git repo is present, run git init at the project/workspace root before building so Codex app git-backed features are available. Never run git init inside a nested subdirectory when the current workspace already belongs to a parent repo.
• Look for .xcworkspace, .xcodeproj, and Package.swift.
• If more than one candidate exists, explain the default choice and the ambiguity.

2. Resolve the runnable target and process name.

• For Xcode, list schemes and prefer the app-producing scheme unless the user names another one.
• For SwiftPM, identify executable products when possible.
• Split SwiftPM launch handling by product type:
• use raw executable launch only for true command-line tools,
• use a generated project-local .app bundle for AppKit/SwiftUI GUI apps.
• Determine the app/process name to kill before relaunching.

3. Create or update script/build_and_run.sh.

• Make the script project-specific and executable.
• It should always:

1. stop the existing running app/process if present, 2. build the macOS target, 3. launch the freshly built app or executable.

• Add optional flags for debugging/log inspection:
• --debug to launch under lldb or attach the debugger
• --logs to stream process logs after launch
• --telemetry to stream unified logs filtered to the app subsystem/category
• --verify to launch the app and confirm the process exists with pgrep -x <AppName>
• Keep the default no-flag path simple: kill, build, run.
• Prefer writing one script that owns this workflow instead of repeatedly asking the agent to manually run swift build, locate the artifact, then invoke an ad hoc run command.
• For SwiftPM GUI apps, make the script build the product, create dist/<AppName>.app, copy the binary to Contents/MacOS/<AppName>, generate a minimal Contents/Info.plist with CFBundlePackageType=APPL, CFBundleExecutable, CFBundleIdentifier, CFBundleName, LSMinimumSystemVersion, and NSPrincipalClass=NSApplication, then launch with /usr/bin/open -n <bundle>.
• For SwiftPM GUI --logs and --telemetry, launch the bundle with /usr/bin/open -n first, then stream unified logs with /usr/bin/log stream --info ....
• Do not recommend direct SwiftPM executable launch for AppKit/SwiftUI GUI apps.
• Use references/run-button-bootstrap.md as the canonical source for the

script shape and exact environment file format. Do not fork a second authoritative snippet in another skill or command.

• Keep the run script outside app source. It belongs in script/build_and_run.sh, not in App/, Views/, Models/, Stores/, Services/, or Support/.

4. Write .codex/environments/environment.toml at the project root once the script exists.

• Use this exact placement: .codex/environments/environment.toml.
• Use the exact action shape in references/run-button-bootstrap.md.
• This file is what gives the user a Codex app Run button wired to the script.
• If the project already has this file, update the Run action command to point at ./script/build_and_run.sh instead of creating a duplicate action.
• Keep this Codex environment config separate from Swift app source files.

5. Build and run through the script.

• Default to ./script/build_and_run.sh.
• Use ./script/build_and_run.sh --debug, --logs, --telemetry, or --verify when the user asks for debugger/log/telemetry/process verification support.

6. Summarize failures correctly.

• Classify the blocker as compiler, linker, signing, build settings, missing SDK/toolchain, script bug, or runtime launch.
• Quote the smallest useful error snippet and explain what it means.

7. Debug the right way.

• Use the script's --logs or --telemetry mode for config, entitlement, sandbox, and action-event verification.
• For SwiftPM GUI apps, if the app bundle launches but its window still does not come forward, check whether the entrypoint needs NSApp.setActivationPolicy(.regular) and NSApp.activate(ignoringOtherApps: true).
• Use the script's --debug mode or direct lldb if symbolized crash debugging is needed.
• If the user needs to instrument and verify specific window, sidebar, menu, or menu bar actions, switch to telemetry.
• Keep evidence tight and user-facing.

8. Use Xcode-aware MCP tooling only when it helps.

• If the user explicitly asks for XcodeBuildMCP and it is already available, prefer it over ad hoc setup.
• Use the MCP for Xcode-aware discovery or debug/logging workflows when the available tool surface clearly matches the task.
• Fall back to shell commands immediately when the MCP does not provide a clean macOS path.

Preferred Commands

• Project discovery:
• find . -name '*.xcworkspace' -o -name '*.xcodeproj' -o -name 'Package.swift'
• Scheme discovery:
• xcodebuild -list -workspace <workspace>
• xcodebuild -list -project <project>
• Build/run:
• ./script/build_and_run.sh
• ./script/build_and_run.sh --debug
• ./script/build_and_run.sh --logs
• ./script/build_and_run.sh --telemetry
• ./script/build_and_run.sh --verify

References

• references/run-button-bootstrap.md: canonical build_and_run.sh and .codex/environments/environment.toml contract.

Guardrails

• Prefer the narrowest command that proves or disproves the current theory.
• Do not leave the user with a one-off manual command chain once a stable build_and_run.sh script can own the workflow.
• Do not write .codex/environments/environment.toml before the run script exists, and do not point the Run action at a stale script path.
• Do not launch a SwiftUI/AppKit SwiftPM GUI app as a raw executable unless the user explicitly wants to diagnose that failure mode: it can produce no Dock icon, no foreground activation, and missing bundle identifier warnings. Keep raw executable launch only for true command-line tools.
• Do not claim UI state you cannot inspect directly.
• Do not describe mobile or simulator workflows as if they apply to macOS.
• If build output is huge, summarize the first real blocker and point to follow-up commands.

Output Expectations

Provide:

• the detected project type
• the script path and Codex environment action you configured, if applicable
• the command you ran
• whether build and launch succeeded
• the top blocker if they failed
• the smallest sensible next action

Run Button Bootstrap

This is the canonical bootstrap contract for the macOS Build plugin's local run loop.

When a project does not already have an established macOS run entrypoint:

1. Create one project-local script/build_and_run.sh. 2. Make it executable. 3. Use it as the single kill + build + run entrypoint. 4. Support optional --debug, --logs, --telemetry, and --verify flags. 5. Write .codex/environments/environment.toml so the Codex app exposes a Run action wired to that script.

script/build_and_run.sh

Use one project-specific script with a tiny mode switch and a default no-flag path that just kills, builds, and launches. Keep raw executable launch only for true command-line tools. For SwiftPM AppKit/SwiftUI GUI apps, stage a project-local .app bundle and launch that bundle with /usr/bin/open -n.

SwiftPM CLI executable

Use this shape for true command-line tools:

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

MODE="${1:-run}"
APP_NAME="MyTool"

pkill -x "$APP_NAME" >/dev/null 2>&1 || true

swift build
APP_BINARY="$(swift build --show-bin-path)/$APP_NAME"

case "$MODE" in
  run)
    "$APP_BINARY"
    ;;
  --debug|debug)
    lldb -- "$APP_BINARY"
    ;;
  --logs|logs)
    "$APP_BINARY" &
    /usr/bin/log stream --info --style compact --predicate "process == \"$APP_NAME\""
    ;;
  --telemetry|telemetry)
    "$APP_BINARY" &
    /usr/bin/log stream --info --style compact --predicate "subsystem == \"com.example.MyTool\""
    ;;
  --verify|verify)
    "$APP_BINARY" &
    sleep 1
    pgrep -x "$APP_NAME" >/dev/null
    ;;
  *)
    echo "usage: $0 [run|--debug|--logs|--telemetry|--verify]" >&2
    exit 2
    ;;
esac

SwiftPM AppKit/SwiftUI GUI app

Use this shape for SwiftPM GUI apps so they launch as a real foreground app bundle with Dock activation and bundle metadata:

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

MODE="${1:-run}"
APP_NAME="MyApp"
BUNDLE_ID="com.example.MyApp"
MIN_SYSTEM_VERSION="14.0"

ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
DIST_DIR="$ROOT_DIR/dist"
APP_BUNDLE="$DIST_DIR/$APP_NAME.app"
APP_CONTENTS="$APP_BUNDLE/Contents"
APP_MACOS="$APP_CONTENTS/MacOS"
APP_BINARY="$APP_MACOS/$APP_NAME"
INFO_PLIST="$APP_CONTENTS/Info.plist"

pkill -x "$APP_NAME" >/dev/null 2>&1 || true

swift build
BUILD_BINARY="$(swift build --show-bin-path)/$APP_NAME"

rm -rf "$APP_BUNDLE"
mkdir -p "$APP_MACOS"
cp "$BUILD_BINARY" "$APP_BINARY"
chmod +x "$APP_BINARY"

cat >"$INFO_PLIST" <<PLIST
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>CFBundleExecutable</key>
  <string>$APP_NAME</string>
  <key>CFBundleIdentifier</key>
  <string>$BUNDLE_ID</string>
  <key>CFBundleName</key>
  <string>$APP_NAME</string>
  <key>CFBundlePackageType</key>
  <string>APPL</string>
  <key>LSMinimumSystemVersion</key>
  <string>$MIN_SYSTEM_VERSION</string>
  <key>NSPrincipalClass</key>
  <string>NSApplication</string>
</dict>
</plist>
PLIST

open_app() {
  /usr/bin/open -n "$APP_BUNDLE"
}

case "$MODE" in
  run)
    open_app
    ;;
  --debug|debug)
    lldb -- "$APP_BINARY"
    ;;
  --logs|logs)
    open_app
    /usr/bin/log stream --info --style compact --predicate "process == \"$APP_NAME\""
    ;;
  --telemetry|telemetry)
    open_app
    /usr/bin/log stream --info --style compact --predicate "subsystem == \"$BUNDLE_ID\""
    ;;
  --verify|verify)
    open_app
    sleep 1
    pgrep -x "$APP_NAME" >/dev/null
    ;;
  *)
    echo "usage: $0 [run|--debug|--logs|--telemetry|--verify]" >&2
    exit 2
    ;;
esac

Launching a SwiftPM GUI binary directly can produce no Dock icon, no foreground activation, and missing bundle identifier warnings. If the .app bundle opens but the main window still does not come forward, the app entrypoint may need NSApp.setActivationPolicy(.regular) and NSApp.activate(ignoringOtherApps: true).

Adapt the build step for Xcode projects by replacing swift build with xcodebuild -project ... or xcodebuild -workspace ..., then launch the built .app binary from DerivedData or a deterministic project-local build path. Keep the one-script interface and mode flags the same.

.codex/environments/environment.toml

Write the environment file at this exact path:

.codex/environments/environment.toml

with this action shape:

# 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 to point at ./script/build_and_run.sh instead of adding a duplicate.