mcpField
D
debugger-agent

debugger-agent

github.com/patrickserranoDevelopment1367 installsUpdated 41w ago
Repository

About debugger-agent

debugger-agent is a workflow skill for building, running, and debugging iOS apps in a booted simulator. It guides developers through simulator UI interaction and log capture using Xcode command-line tools.

Key features

  1. 01Build iOS projects with xcodebuild
  2. 02Install and launch apps in simulators
  3. 03Stream app or simulator logs
  4. 04Capture screenshots and video
  5. 05Open deep links and send notifications

Use cases

  1. 01Reproducing an iOS app issue in a simulator
  2. 02Inspecting app logs during a test run
  3. 03Capturing simulator UI for debugging

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/patrickserrano/skills --skill debugger-agent

After installing, type/debugger-agentin Claude Code to confirm it loaded.

Details

From the project README

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

TaskCommand
List simulatorsxcrun simctl list devices
Boot simulatorxcrun simctl boot "iPhone 15 Pro"
Shutdown simulatorxcrun simctl shutdown booted
Erase simulatorxcrun simctl erase booted
Install appxcrun simctl install booted /path/to/App.app
Uninstall appxcrun simctl uninstall booted com.example.app
Launch appxcrun simctl launch booted com.example.app
Terminate appxcrun simctl terminate booted com.example.app
Get app containerxcrun simctl get_app_container booted com.example.app

Comments

Markdown supported