# iOS Simulator Skill for Claude Code

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](https://github.com/conorluddy/xc-mcp)


> [!WARNING]
> You want to take the `ios-simulator-skill` directory from this repo and drop it into your skills directory - not this entire repo. I'll update this soon with an easier approach. Feel free to fork this and get Claude to adjust it to your specific needs.


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](https://github.com/conorluddy/xclaude-plugin)

## What It Does

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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Run health check
bash ~/.claude/skills/ios-simulator-skill/scripts/sim_health_check.sh

# Checks: macOS, Xcode, simctl, IDB, Python, simulators, packages
```

### Script Help

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

### Not Finding Elements

```bash
# 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

> [!WARNING]
> I appreciate contributions, but please note that this repo and my other public repos are far down in the priority queue of what I'm working on, so I'll be slow to review anything. Your best bet is really just to fork the repo and customise it to your own needs.

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.**