iOS Simulator Skill for Claude Code

Name: ios-simulator-skill
Rating: 5 (171 reviews)
Author: conorluddy

Production-ready automation for iOS app testing and building. 21 scripts optimized for both human developers and AI agents.

This is basically a Skill version of my XCode MCP: https://github.com/conorluddy/xc-mcp

MCPs load a lot of tokens into the context window when they're active, but also seem to work really well. Skills don't load in any context. I'll make a plugin next and try to find the balance...

Updated: The Plugin version lets you easily disable MCPs for different tool groups. Optimise your context window by only enabling the tools you're actively using, such as xcodebuild: https://github.com/conorluddy/xclaude-plugin

What It Does

Instead of pixel-based navigation that breaks when UI changes:

# Fragile - breaks if UI changes
idb ui tap 320 400
Robust - finds by meaning
python scripts/navigator.py --find-text "Login" --tap

Uses semantic navigation on accessibility APIs to interact with elements by their meaning, not coordinates. Works across different screen sizes and survives UI redesigns.

Features

21 production scripts for building, testing, and automation
Semantic navigation - find elements by text, type, or ID
Token optimized - 96% reduction vs raw tools (3-5 lines default)
Zero configuration - works immediately on macOS with Xcode
Structured output - JSON and formatted text, easy to parse
Auto-UDID detection - no need to specify device each time
Batch operations - boot, delete, erase multiple simulators at once
Comprehensive testing - WCAG compliance, visual diffs, accessibility audits
CI/CD ready - JSON output, exit codes, automated device lifecycle

Installation

As Claude Code Skill

# Personal installation
git clone https://github.com/conorluddy/ios-simulator-skill.git ~/.claude/skills/ios-simulator-skill
Project installation
git clone https://github.com/conorluddy/ios-simulator-skill.git .claude/skills/ios-simulator-skill

Restart Claude Code. The skill loads automatically.

From Release

# Download latest release
curl -L https://github.com/conorluddy/ios-simulator-skill/releases/download/vX.X.X/ios-simulator-skill-vX.X.X.zip -o skill.zip
Extract
unzip skill.zip -d ~/.claude/skills/ios-simulator-skill

Prerequisites

macOS 12+
Xcode Command Line Tools (xcode-select --install)
Python 3
IDB (optional, for interactive features: brew tap facebook/fb && brew install idb-companion)

Quick Start

# 1. Check environment
bash ~/.claude/skills/ios-simulator-skill/scripts/sim_health_check.sh
2. Launch your app
python ~/.claude/skills/ios-simulator-skill/scripts/app_launcher.py --launch com.example.app
3. See what's on screen
python ~/.claude/skills/ios-simulator-skill/scripts/screen_mapper.py
Output:
Screen: LoginViewController (45 elements, 7 interactive)
Buttons: "Login", "Cancel", "Forgot Password"
TextFields: 2 (0 filled)
4. Tap login button
python ~/.claude/skills/ios-simulator-skill/scripts/navigator.py --find-text "Login" --tap
5. Enter text
python ~/.claude/skills/ios-simulator-skill/scripts/navigator.py --find-type TextField --enter-text "user@test.com"
6. Check accessibility
python ~/.claude/skills/ios-simulator-skill/scripts/accessibility_audit.py

21 Scripts Organized by Category

Build & Development

build_and_test.py - Build projects, run tests, parse results
log_monitor.py - Real-time log monitoring

Navigation & Interaction

screen_mapper.py - Analyze current screen
navigator.py - Find and interact with elements
gesture.py - Swipes, scrolls, pinches
keyboard.py - Text input and hardware buttons
app_launcher.py - App lifecycle control

Testing & Analysis

accessibility_audit.py - WCAG compliance checking
visual_diff.py - Screenshot comparison
test_recorder.py - Automated test documentation
app_state_capture.py - Debugging snapshots
sim_health_check.sh - Environment verification

Advanced Testing & Permissions

clipboard.py - Clipboard management
status_bar.py - Status bar control
push_notification.py - Push notifications
privacy_manager.py - Permission management

Device Lifecycle

simctl_boot.py - Boot simulator
simctl_shutdown.py - Shutdown simulator
simctl_create.py - Create simulator
simctl_delete.py - Delete simulator
simctl_erase.py - Factory reset

See SKILL.md for complete reference.

How It Works with Claude Code

Claude Code automatically detects when to use this skill based on your request. You don't need to manually invoke it.

Example conversation:

You: "Set up my iOS app for testing" Claude: [Uses simctl_boot.py and app_launcher.py automatically] You: "Tap the login button" Claude: [Uses navigator.py to find and tap]

You: "Check if the form is accessible" Claude: [Uses accessibility_audit.py]

You can also run scripts manually when needed.

Usage Examples

Example 1: Login Flow

# Launch app
python scripts/app_launcher.py --launch com.example.app
Map screen to find fields
python scripts/screen_mapper.py
Enter credentials
python scripts/navigator.py --find-type TextField --index 0 --enter-text "user@test.com"
python scripts/navigator.py --find-type SecureTextField --enter-text "password"
Tap login
python scripts/navigator.py --find-text "Login" --tap
Verify accessibility
python scripts/accessibility_audit.py

Example 2: Test Documentation

# Record test execution
python scripts/test_recorder.py --test-name "Login Flow" --output test-reports/
Generates:
- Screenshots per step
- Accessibility trees
- Markdown report with timing

Example 3: Visual Testing

# Capture baseline
python scripts/app_state_capture.py --output baseline/
Make changes...
Compare
python scripts/visual_diff.py baseline/screenshot.png current/screenshot.png

Example 4: Permission Testing

# Grant permissions
python scripts/privacy_manager.py --bundle-id com.example.app --grant camera,location
Test app behavior with permissions...
Revoke permissions
python scripts/privacy_manager.py --bundle-id com.example.app --revoke camera,location

Example 5: Device Lifecycle in CI/CD

# Create test device
DEVICE_ID=$(python scripts/simctl_create.py --device "iPhone 16 Pro" --json | jq -r '.new_udid')
Run tests
python scripts/build_and_test.py --project MyApp.xcodeproj
Clean up
python scripts/simctl_delete.py --udid $DEVICE_ID --yes

Design Principles

Semantic Navigation: Find elements by meaning (text, type, ID) not pixel coordinates. Survives UI changes and works across device sizes.

Token Efficiency: Default output is 3-5 lines. Use --verbose for details or --json for machine parsing. 96% reduction vs raw tools.

Accessibility-First: Built on iOS accessibility APIs for reliability. Better for users with accessibility needs and more robust for automation.

Zero Configuration: Works immediately on any macOS with Xcode. No complex setup, no configuration files.

Structured Data: Scripts output JSON or formatted text, not raw logs. Easy to parse, integrate, and understand.

Auto-Learning: Build system learns your device preference and remembers it for next time.

Requirements

System:

macOS 12 or later
Xcode Command Line Tools
Python 3

Optional:

IDB (for interactive features)
Pillow (for visual_diff.py: pip3 install pillow)

Documentation

SKILL.md - Complete script reference and table of contents
CLAUDE.md - Architecture and developer guide
references/ - Deep documentation on specific topics
examples/ - Complete automation workflows

Output Efficiency

All scripts minimize output by default:

| Task | Raw Tools | This Skill | Savings | |------|-----------|-----------|---------| | Screen analysis | 200+ lines | 5 lines | 97.5% | | Find & tap button | 100+ lines | 1 line | 99% | | Enter text | 50+ lines | 1 line | 98% | | Login flow | 400+ lines | 15 lines | 96% |

This efficiency keeps AI agent conversations focused and cost-effective.

Troubleshooting

Environment Issues

# Run health check
bash ~/.claude/skills/ios-simulator-skill/scripts/sim_health_check.shChecks: macOS, Xcode, simctl, IDB, Python, simulators, packages

Script Help

# All scripts support --help
python scripts/navigator.py --help
python scripts/accessibility_audit.py --help

Not Finding Elements

# Use verbose mode to see all elements
python scripts/screen_mapper.py --verbose
Check for exact text match
python scripts/navigator.py --find-text "Exact Button Text" --tap

Contributing

Contributions should:

Maintain token efficiency (minimal default output)
Follow accessibility-first design
Support --help documentation
Support --json for CI/CD
Pass Black formatter and Ruff linter
Include type hints
Update SKILL.md

License

MIT License - Allows commercial use and distribution.

Support

Issues: Create GitHub issue with reproduction steps
Documentation: See SKILL.md and references/
Examples: Check examples/ directory
Skills Docs: https://docs.claude.com/en/docs/claude-code/skills

---

Built for AI agents. Optimized for developers.

--- Tranlated By Open Ai Tx | Last indexed: 2025-12-18 ---