iOS Debugger Agent

Overview

Build and run iOS projects on a booted simulator, interact with the UI, and capture logs for debugging.

Prerequisites

• Xcode installed with command-line tools
• A booted iOS simulator (check with xcrun simctl list devices)
• Project with .xcodeproj or .xcworkspace

Core Workflow

1) Discover the booted simulator

xcrun simctl list devices | grep -E "Booted"

If none are booted, ask the user to boot one:

xcrun simctl boot "iPhone 15 Pro"

2) Build the project

For a workspace:

xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15 Pro' build

For a project:

xcodebuild -project MyApp.xcodeproj -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 15 Pro' build

3) Install and launch the app

Find the built app:

find ~/Library/Developer/Xcode/DerivedData -name "*.app" -path "*Debug-iphonesimulator*" | head -1

Install on simulator:

xcrun simctl install booted /path/to/MyApp.app

Launch the app:

xcrun simctl launch booted com.example.MyApp

4) Capture logs

Stream logs from the app:

xcrun simctl spawn booted log stream --predicate 'subsystem == "com.example.MyApp"' --level debug

Or capture all simulator logs:

xcrun simctl spawn booted log stream --level debug

UI Interaction

Take a screenshot

xcrun simctl io booted screenshot screenshot.png

Record video

xcrun simctl io booted recordVideo video.mp4
# Press Ctrl+C to stop recording

Open a URL in the simulator

xcrun simctl openurl booted "myapp://deeplink"

Send push notification

xcrun simctl push booted com.example.MyApp notification.apns

Troubleshooting

• Build fails: Check scheme name with xcodebuild -list
• App won’t launch: Verify bundle ID with defaults read /path/to/MyApp.app/Info.plist CFBundleIdentifier
• Simulator not found: List available simulators with xcrun simctl list devices available
• Clean build: xcodebuild clean or delete DerivedData

Common Commands Reference