Macos runtime debugger

Skill Xopoko/build-swift-apps/skills/macos-runtime-debugger

Swift-focused AI agent skills for iOS and macOS: build, debug, simulator, SwiftUI, Xcode, App Store workflows. Part of Plug'n Skills.

Install

npx -y skills add Xopoko/build-swift-apps --skill macos-runtime-debugger

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

Build, run, and debug local macOS apps or desktop executables with shell-first Xcode/Swift workflows. Use for Mac app builds, launch scripts, compiler/linker/startup failures, logs, telemetry, or desktop runtime debugging.

SKILL.md

3.4 KB, 762 tokens by cl100k_base, as published. Nobody here has run it

macOS Runtime Debugger

Create one project-local script/build_and_run.sh and use it as the default build/run/debug path. In Codex app sessions, optionally wire the same script to .codex/environments/environment.toml.

Workflow

Discover project shape:
```
git rev-parse --is-inside-work-tree
find . -name '*.xcworkspace' -o -name '*.xcodeproj' -o -name 'Package.swift'
```
If no git repo exists and a host tool needs one, run git init at the workspace root, never inside a nested repo.
Resolve runnable target/process:
- Xcode: list schemes and prefer the app-producing scheme unless named.
- SwiftPM CLI: run the executable.
- SwiftPM AppKit/SwiftUI GUI: stage a project-local .app bundle and launch with /usr/bin/open -n; do not run as a raw executable.
Create/update executable script/build_and_run.sh. It should kill existing process, build, launch, and support optional --debug, --logs, --telemetry, and --verify.
Use references/run-button-bootstrap.md as the canonical script/environment shape; do not duplicate a second full snippet.
In Codex app sessions, create/update .codex/environments/environment.toml only after the script exists; point the Run action at ./script/build_and_run.sh.

Run through the script:

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

Classify failures as compiler, linker, signing, build settings, missing SDK/toolchain, script bug, or runtime launch. Quote the smallest useful error.

Script Requirements

Keep it outside app source in script/build_and_run.sh.
Xcode projects use xcodebuild.
SwiftPM command-line tools use swift build then executable launch.
SwiftPM GUI apps create dist/<AppName>.app, copy the binary to Contents/MacOS/, generate minimal Info.plist (APPL, executable, identifier, name, minimum system version, NSApplication), then launch with /usr/bin/open -n.
For GUI logs/telemetry, launch the bundle first, then stream unified logs.
--verify should confirm process existence with pgrep -x <AppName>.

Debugging

Use --logs/--telemetry for config, entitlements, sandbox, and action-event proof.
If a SwiftPM GUI bundle launches but does not foreground, check NSApp.setActivationPolicy(.regular) and NSApp.activate(ignoringOtherApps: true).
Use --debug or direct lldb for symbolized crash debugging.
Switch to macos-telemetry-probe when verifying specific window/sidebar/menu/menu-bar actions.
Use Xcode-aware MCP only when explicitly requested and it fits macOS discovery/debugging; fall back to shell when it does not.

Guardrails

Do not leave a one-off command chain when a stable script can own the flow.
Do not write Codex environment config before the script exists.
Do not describe mobile/simulator workflows as macOS workflows.
Do not claim UI state you cannot inspect.

Output

Report detected project type, script/env path configured, command run, build/launch result, top blocker if failed, and the smallest next action.