build-run-debug
Build, run, and debug macOS apps with shell-first Xcode and Swift workflows. Use when launching apps or diagnosing build, startup, or runtime failures.
- License 许可
- MIT
- 最近更新
- 2026-09-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- build-run-debug
- description
- Build, run, and debug macOS apps with shell-first Xcode and Swift workflows. Use when launching apps or diagnosing build, startup, or runtime failures.
02 资源文件 2
- 参考文档agents/openai.yaml301 B
- 参考文档references/run-button-bootstrap.md4.6 KB
03 SKILL.md 正文
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.shas the single kill + build + run entrypoint once it existsxcodebuildfor Xcode workspaces or projectsswift buildplus raw executable launch inside that script for true SwiftPM command-line toolsswift buildplus project-local.appbundle staging and/usr/bin/open -nlaunch 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
-
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 initat the project/workspace root before building so Codex app git-backed features are available. Never rungit initinside a nested subdirectory when the current workspace already belongs to a parent repo. - Look for
.xcworkspace,.xcodeproj, andPackage.swift. - If more than one candidate exists, explain the default choice and the ambiguity.
- Check whether the workspace is already inside a git repo with
-
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
.appbundle for AppKit/SwiftUI GUI apps.
- Determine the app/process name to kill before relaunching.
-
Create or update
script/build_and_run.sh.- Make the script project-specific and executable.
- It should always:
- stop the existing running app/process if present,
- build the macOS target,
- launch the freshly built app or executable.
- Add optional flags for debugging/log inspection:
--debugto launch underlldbor attach the debugger--logsto stream process logs after launch--telemetryto stream unified logs filtered to the app subsystem/category--verifyto launch the app and confirm the process exists withpgrep -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 toContents/MacOS/<AppName>, generate a minimalContents/Info.plistwithCFBundlePackageType=APPL,CFBundleExecutable,CFBundleIdentifier,CFBundleName,LSMinimumSystemVersion, andNSPrincipalClass=NSApplication, then launch with/usr/bin/open -n <bundle>. - For SwiftPM GUI
--logsand--telemetry, launch the bundle with/usr/bin/open -nfirst, 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.mdas 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 inApp/,Views/,Models/,Stores/,Services/, orSupport/.
-
Write
.codex/environments/environment.tomlat 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
Runaction command to point at./script/build_and_run.shinstead of creating a duplicate action. - Keep this Codex environment config separate from Swift app source files.
- Use this exact placement:
-
Build and run through the script.
- Default to
./script/build_and_run.sh. - Use
./script/build_and_run.sh --debug,--logs,--telemetry, or--verifywhen the user asks for debugger/log/telemetry/process verification support.
- Default to
-
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.
-
Debug the right way.
- Use the script's
--logsor--telemetrymode 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)andNSApp.activate(ignoringOtherApps: true). - Use the script's
--debugmode or directlldbif 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.
- Use the script's
-
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: canonicalbuild_and_run.shand.codex/environments/environment.tomlcontract.
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.shscript can own the workflow. - Do not write
.codex/environments/environment.tomlbefore 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
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Create or update a Codex skill with appropriately scoped instructions and any needed supporting resources.
review-agent
Perform a read-only, defect-first review of a specified code change and return every actionable finding. Use when another agent delegates review of uncommitted changes, a base-branch diff, a commit, or custom review instructions.
plugin-creator
Create and scaffold plugin directories for Codex with a required `.codex-plugin/plugin.json`, optional plugin folders/files, valid manifest defaults, and personal-marketplace entries by default. Use when Codex needs to create a new personal plugin, add optional plugin structure, generate or update marketplace entries for plugin ordering and availability metadata, or update an existing local plugin during development with the CLI-driven cachebuster and reinstall flow.
openai-docs
Use for Codex models/pricing, scheduled tasks, skills, settings, setup, troubleshooting, customization, automations, and self-knowledge—including 'you,' 'your,' 'this app,' or 'this coding agent' when they refer to Codex—and for OpenAI APIs/products and ChatGPT Work. Also use for model choice/migration, prompting, SDKs, Responses, Realtime, agents, evals, and Chat/Work/Codex comparisons. Do not use for generic app/software tasks that merely mention Codex.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.