iOS Simulator Tools for Amp

A collection of Python tools for iOS Simulator automation, designed for use with Amp.

Derived from ios-simulator-skill by Conor Luddy, adapted for the Amp toolbox protocol.

Features

• 18 production tools for building, testing, and automation
• Semantic navigation - find elements by text, type, or ID
• Token optimized - concise output for AI agent consumption
• 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

Prerequisites

• macOS with Xcode installed
• Python 3.x
• iOS Simulator

Installation

1. Clone this repository:

   git clone https://github.com/user/amp-tools-ios.git

2. Install dependencies:

   cd amp-tools-ios
   pip install

3. Configure Amp to use the toolbox by setting the AMP_TOOLBOX environment variable to point to the tools directory:

   Option A: Shell configuration (recommended)

   Add to your ~/.zshrc or ~/.bashrc:

   export AMP_TOOLBOX="/path/to/amp-tools-ios/tools"

   To combine with other toolboxes, use colon-separated paths:

   export AMP_TOOLBOX="/path/to/amp-tools-ios/tools:$HOME/.config/amp/tools"

   Option B: VS Code / Cursor settings

   Add to your settings.json:

   {
     "terminal.integrated.env.osx": {
       "AMP_TOOLBOX": "/path/to/amp-tools-ios/tools"
     }
   }

4. Restart Amp to discover the tools.

Tools

Build & Development

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

Navigation & Interaction

Tool	Description
screen_mapper.py	Analyze current screen and list interactive elements
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

Tool	Description
accessibility_audit.py	WCAG compliance checking
visual_diff.py	Screenshot comparison
test_recorder.py	Automated test documentation
app_state_capture.py	Debugging snapshots

Device Lifecycle

Tool	Description
simctl.py	Unified simulator management (boot, shutdown, create, delete, erase, list)
sim_health_check.py	Environment verification

System Control

Tool	Description
clipboard.py	Clipboard operations
privacy_manager.py	Privacy permissions management
push_notification.py	Send push notifications
status_bar.py	Status bar customization

Usage

Each tool follows the Amp toolbox protocol:

# Describe tool capabilities
TOOLBOX_ACTION=describe python tools/screen_mapper.py

# Execute tool with JSON parameters
echo '{"verbose": true}' | TOOLBOX_ACTION=execute python tools/screen_mapper.py

Example: Analyze Screen

echo '{}' | TOOLBOX_ACTION=execute python tools/screen_mapper.py

Output:

Screen: LoginViewController (45 elements, 12 interactive)
Buttons: "Login", "Sign Up", "Forgot Password"
TextFields: 2 (0 filled)
Navigation: NavBar: "Welcome"
Focusable: 8 elements

Design Principles

• Semantic Navigation: Find elements by meaning (text, type, ID) not pixel coordinates
• Token Efficiency: Default output is concise; use --verbose for details or --json for machine parsing
• Accessibility-First: Built on iOS accessibility APIs for reliability
• Structured Data: Tools output JSON or formatted text, not raw logs

Documentation

• Amp Manual - Amp documentation and tools configuration
• ios-simulator-skill - Original project for Claude Code

Acknowledgements

This project is derived from ios-simulator-skill by Conor Luddy. The original project provides iOS Simulator automation for Claude Code; this adaptation brings the same capabilities to Amp using its toolbox protocol.

License

MIT License - see LICENSE for details.