ios-debugger-agent

The iOS Debugger Agent manages the interaction between AI assistants and local Xcode environments. It provides a structured interface for deploying apps to booted iOS simulators, navigating application hierarchies, and analyzing runtime logs. By orchestrating the XcodeBuildMCP protocol, the agent automates the discovery of simulator states, manages project schemes, and executes UI operations such as tapping, text entry, and gesture tracking. It bridges the gap between raw source code and dynamic simulator behavior, allowing developers to inspect UI states, confirm layout rendering, and capture debug output without manually switching contexts between the code editor and the simulator application. This agent transforms high-level user goals into specific simulator commands, ensuring that build parameters, bundle identifiers, and session defaults remain synchronized during the testing process.

When to Use This Skill

• •Verifying UI layout responsiveness on a specific simulated device
• •Reproducing crash reports by capturing live simulator logs
• •Testing user flows such as login or data entry on a fresh build
• •Confirming that recent code changes reflect correctly in the app interface

How to Invoke This Skill

Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:

• “Debug the current iOS build on the simulator
• “Show me the UI hierarchy for the running app
• “Start capturing logs and try to reproduce the login flow
• “Find the booted simulator and build the app
• “Tap the submit button and check for error logs

Pro Tips

• 💡Always ensure an iOS simulator is pre-booted to expedite the debugging process; the skill can discover existing booted instances.
• 💡Leverage the `session-set-defaults` function to define your project path, scheme, and simulator ID once per session to reduce repetitive inputs.
• 💡Combine UI interaction requests with log capture to get a comprehensive view of what happened leading up to an issue.

What this skill does

• •Identify and target active iOS simulators
• •Automate build and launch cycles for specific app schemes
• •Inspect UI element hierarchies via screen description tools
• •Execute remote taps, text inputs, and navigation gestures
• •Stream and summarize console logs directly from the simulator

When not to use it

• ✕When physical hardware device testing or debugging is required
• ✕If the build environment or Xcode project configuration is corrupted or missing dependencies
• ✕For tasks requiring non-simulated features like push notification hardware integration

Example workflow

1. Confirm a simulator is currently booted
2. Set the project path, scheme, and simulator ID as session defaults
3. Build the application and launch it within the simulator environment
4. Use describe_ui to identify the target interactable elements
5. Perform the necessary UI actions and initiate log capture
6. Stop log capture and analyze the resulting output for errors

Prerequisites

• –Xcode installed on macOS
• –An existing iOS project with valid scheme configurations
• –A booted iOS simulator instance

Pitfalls & limitations

• !Attempts to boot simulators automatically may fail due to system permissions
• !UI elements might report as non-hittable if the layout has not finished rendering
• !Incorrect scheme or bundle ID settings will cause build or launch failures

FAQ

How it compares

Unlike manual testing which requires constant context switching, this agent maintains persistent state information, allowing it to execute multi-step diagnostic workflows faster and with higher accuracy.

Source & trust

Recommended Rules

Recommended Workflows

Recommended MCP Servers