build-debug-macos

name	build-debug-macos
description	Build, launch, and debug macOS apps: run the target command, capture logs, capture screenshots, and summarize UI or runtime regressions.

Build Debug (macOS)

Overview

Use this skill to create deterministic artifacts for macOS app debugging without hardcoding any one repo, build system, or app name. Configure the run command and app name for the current project, then use the helper script to capture logs and screenshots.

Prepare the Session

Before running anything, determine:

1. A one-shot RUN_CMD that builds and launches the app without opening an interactive watcher.
2. APP_NAME — the process name for pgrep and window activation.
3. Optionally, a LOG_PREDICATE for log stream.

Prefer a command that exits after launch. If the normal workflow uses a long-running watcher, derive a non-interactive build-and-launch command for artifact capture.

Workflow

Run the macOS helper against the project root:

RUN_CMD='xcodebuild -scheme Example build && open build/Debug/Example.app' \
APP_NAME='Example' \
${CLAUDE_SKILL_DIR}/scripts/capture_macos_debug.sh /path/to/repo

Environment variables:

• RUN_CMD (required): Build/launch command executed with bash -lc.
• APP_NAME (required): Process name used for pgrep and window activation.
• LOG_PREDICATE (optional): Custom log stream predicate. Defaults to process == "APP_NAME".
• WAIT_FOR_SECONDS (optional): Seconds to wait for the app to appear. Defaults to 10.
• OUT_DIR (optional): Artifact directory. Defaults to /tmp/apple-macos-debug.

The script prints:

• APP_PID
• APP_RUNNING
• RUN_STATUS
• RUN_EXIT_CODE
• RUN_LOG
• LOG_FILE
• SCREENSHOT

For basic UI interaction, use AppleScript UI scripting after granting Accessibility permission to Terminal:

osascript -e 'tell application "System Events" to click button "Continue" of window 1 of process "Example"'

Prefer XCTest UI tests when repeated or robust macOS automation is needed.

Reporting

Always return:

1. Build/run status, including whether RUN_CMD exited, failed, or was still running during capture.
2. Artifact paths.
3. UI verdict: expected or unexpected.
4. Specific mismatch list tied to screenshots or logs.
5. Missing prerequisites or gaps such as no Accessibility permission or screenshot capture failure.