# conorluddy/ios-simulator-skill architecture

> Architecture diagram of the GitHub repository conorluddy/ios-simulator-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/conorluddy/ios-simulator-skill
- Repository: https://github.com/conorluddy/ios-simulator-skill

## Overview

This repository is a Claude Code skill: developers or agents invoke focused Python commands to build/test Xcode projects or control and inspect iOS simulators. The main interaction path is semantic UI navigation and device/app control, with accessibility, visual, log, and app-state analysis as diagnostic branches. Build results are summarized for on-demand detail; HangBuster is a separate hang-monitoring workflow. Shared simulator utilities support the scripts. Relationships among unsampled features are included only where the README documents them; source excerpts are partial.

Main entry points: [`ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/builder.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/builder.py) (Build and test), [`ios-simulator-skill/skills/ios-simulator-skill/scripts/navigator.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/navigator.py) (Semantic navigation), [`ios-simulator-skill/skills/ios-simulator-skill/scripts/hang_watcher.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/hang_watcher.py) (Hang monitoring), [`ios-simulator-skill/skills/ios-simulator-skill/scripts/common`](https://github.com/conorluddy/ios-simulator-skill/tree/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/common) (Simulator utilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Xcode builds"]
  node_build_exec["Build and test<br/>[builder.py]"]
  node_build_config["Build configuration<br/>[config.py]"]
  node_xcresult_cache[("Result cache<br/>[cache.py]")]
  node_xcresult_parse["Result parser<br/>[xcresult.py]"]
  node_build_report["Build reporting<br/>[reporter.py]"]
end

subgraph group_devices["Simulator control"]
  node_sim_lifecycle["Simulator lifecycle<br/>[simctl_boot.py]"]
  node_sim_selection["Simulator selection"]
  node_app_control["App launcher<br/>[app_launcher.py]"]
  node_device_state["Device settings<br/>[appearance.py]"]
  node_location_control["Location simulation<br/>[location.py]"]
  node_privacy_control["Privacy settings<br/>[privacy_manager.py]"]
end

subgraph group_interaction["UI interaction"]
  node_screen_navigation["Semantic navigation<br/>[navigator.py]"]
  node_screen_mapping["Screen mapping<br/>[screen_mapper.py]"]
  node_gestures["Gestures and keyboard<br/>[gesture.py]"]
end

subgraph group_analysis["Testing and analysis"]
  node_accessibility["Accessibility audit"]
  node_localization["Localization audit"]
  node_visual_diff["Visual comparison<br/>[visual_diff.py]"]
  node_state_capture["App state capture"]
  node_logs["Log monitoring<br/>[log_monitor.py]"]
  node_hang_watcher["Hang monitoring<br/>[hang_watcher.py]"]
  node_hang_pipeline["Hang analysis pipeline<br/>[hang_pipeline.py]"]
  node_hang_sessions[("Hang session store<br/>[hang_sessions.py]")]
  node_container_inspect["App container inspection<br/>[container.py]"]
  node_model_inspect["Data model inspection<br/>[model_inspector.py]"]
end

subgraph group_shared["Shared runtime"]
  node_shared_sim["Simulator utilities"]
  node_ios_sim_device_utils["Device helpers<br/>[device_utils.py]"]
end

node_developer(("Developer or agent"))
node_xcode_tools["Xcode toolchain"]
node_simctl["simctl"]
node_idb["idb"]

node_developer -->|"runs build or test"| node_build_exec
node_build_exec -->|"invokes xcodebuild"| node_xcode_tools
node_build_exec -->|"loads preferences"| node_build_config
node_build_exec -->|"stores results"| node_xcresult_cache
node_build_exec -->|"parses results"| node_xcresult_parse
node_build_exec -->|"summarizes results"| node_build_report
node_developer -->|"manages devices"| node_sim_lifecycle
node_sim_lifecycle -->|"controls simulators"| node_simctl
node_developer -->|"selects simulator"| node_sim_selection
node_developer -->|"controls apps"| node_app_control
node_app_control -->|"launches and installs"| node_simctl
node_developer -->|"changes device state"| node_device_state
node_developer -->|"sets simulated location"| node_location_control
node_developer -->|"manages permissions"| node_privacy_control
node_developer -->|"finds UI elements"| node_screen_navigation
node_screen_navigation -->|"interacts semantically"| node_idb
node_developer -->|"inspects screen"| node_screen_mapping
node_developer -->|"performs gestures"| node_gestures
node_gestures -->|"sends interaction"| node_idb
node_screen_navigation -->|"imports utilities"| node_shared_sim
node_shared_sim -->|"exports device helpers"| node_ios_sim_device_utils
node_developer -->|"audits accessibility"| node_accessibility
node_developer -->|"audits localization"| node_localization
node_developer -->|"compares screenshots"| node_visual_diff
node_developer -->|"captures diagnostics"| node_state_capture
node_developer -->|"monitors logs"| node_logs
node_developer -->|"monitors hangs"| node_hang_watcher
node_hang_watcher -->|"filters and ranks"| node_hang_pipeline
node_hang_watcher -->|"stores sessions"| node_hang_sessions
node_developer -->|"inspects app data"| node_container_inspect
node_container_inspect -->|"imports utilities"| node_shared_sim
node_developer -->|"inspects data models"| node_model_inspect

click node_build_exec "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/builder.py"
click node_build_config "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/config.py"
click node_xcresult_cache "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/cache.py"
click node_xcresult_parse "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/xcresult.py"
click node_build_report "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/reporter.py"
click node_sim_lifecycle "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/simctl_boot.py"
click node_sim_selection "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/simulator_selector.py"
click node_app_control "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/app_launcher.py"
click node_device_state "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/appearance.py"
click node_location_control "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/location.py"
click node_privacy_control "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/privacy_manager.py"
click node_screen_navigation "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/navigator.py"
click node_screen_mapping "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/screen_mapper.py"
click node_gestures "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/gesture.py"
click node_shared_sim "https://github.com/conorluddy/ios-simulator-skill/tree/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/common"
click node_ios_sim_device_utils "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/common/device_utils.py"
click node_accessibility "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/accessibility_audit.py"
click node_localization "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/localization_audit.py"
click node_visual_diff "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/visual_diff.py"
click node_state_capture "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/app_state_capture.py"
click node_logs "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/log_monitor.py"
click node_hang_watcher "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/hang_watcher.py"
click node_hang_pipeline "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/common/hang_pipeline.py"
click node_hang_sessions "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/common/hang_sessions.py"
click node_container_inspect "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/container.py"
click node_model_inspect "https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/model_inspector.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_build_exec,node_build_config,node_xcresult_cache,node_xcresult_parse,node_build_report toneBlue
class node_sim_lifecycle,node_sim_selection,node_app_control,node_device_state,node_location_control,node_privacy_control toneAmber
class node_screen_navigation,node_screen_mapping,node_gestures toneMint
class node_accessibility,node_localization,node_visual_diff,node_state_capture,node_logs,node_hang_watcher,node_hang_pipeline,node_hang_sessions,node_container_inspect,node_model_inspect toneRose
class node_shared_sim,node_ios_sim_device_utils,node_developer,node_xcode_tools,node_simctl,node_idb toneIndigo
```

## Components

### Xcode builds

- [Build and test](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/builder.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/builder.py`
- [Build configuration](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/config.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/config.py`
- [Result cache](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/cache.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/cache.py`
- [Result parser](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/xcresult.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/xcresult.py`
- [Build reporting](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/reporter.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/reporter.py`

### Simulator control

- [Simulator lifecycle](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/simctl_boot.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/simctl_boot.py`
- [Simulator selection](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/simulator_selector.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/simulator_selector.py`
- [App launcher](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/app_launcher.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/app_launcher.py`
- [Device settings](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/appearance.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/appearance.py`
- [Location simulation](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/location.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/location.py`
- [Privacy settings](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/privacy_manager.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/privacy_manager.py`

### UI interaction

- [Semantic navigation](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/navigator.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/navigator.py`
- [Screen mapping](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/screen_mapper.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/screen_mapper.py`
- [Gestures and keyboard](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/gesture.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/gesture.py`

### Testing and analysis

- [Accessibility audit](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/accessibility_audit.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/accessibility_audit.py`
- [Localization audit](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/localization_audit.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/localization_audit.py`
- [Visual comparison](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/visual_diff.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/visual_diff.py`
- [App state capture](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/app_state_capture.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/app_state_capture.py`
- [Log monitoring](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/log_monitor.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/log_monitor.py`
- [Hang monitoring](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/hang_watcher.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/hang_watcher.py`
- [Hang analysis pipeline](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/common/hang_pipeline.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/common/hang_pipeline.py`
- [Hang session store](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/common/hang_sessions.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/common/hang_sessions.py`
- [App container inspection](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/container.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/container.py`
- [Data model inspection](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/model_inspector.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/model_inspector.py`

### Shared runtime

- [Simulator utilities](https://github.com/conorluddy/ios-simulator-skill/tree/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/common): `ios-simulator-skill/skills/ios-simulator-skill/scripts/common`
- [Device helpers](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/skills/ios-simulator-skill/scripts/common/device_utils.py): `ios-simulator-skill/skills/ios-simulator-skill/scripts/common/device_utils.py`

### Other components

- **Developer or agent**
- **Xcode toolchain**
- **simctl**
- **idb**

## Connections

- Developer or agent → Build and test: runs build or test (evidence: `README.md`)
- Build and test → Xcode toolchain: invokes xcodebuild (evidence: `README.md`)
- Build and test → Build configuration: loads preferences (evidence: `ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/builder.py`)
- Build and test → Result cache: stores results (evidence: `ios-simulator-skill/skills/ios-simulator-skill/scripts/xcode/builder.py`)
- Build and test → Result parser: parses results (evidence: `README.md`)
- Build and test → Build reporting: summarizes results (evidence: `README.md`)
- Developer or agent → Simulator lifecycle: manages devices (evidence: `README.md`)
- Simulator lifecycle → simctl: controls simulators (evidence: `README.md`)
- Developer or agent → Simulator selection: selects simulator (evidence: `README.md`)
- Developer or agent → App launcher: controls apps (evidence: `README.md`)
- App launcher → simctl: launches and installs (evidence: `README.md`)
- Developer or agent → Device settings: changes device state (evidence: `README.md`)
- Developer or agent → Location simulation: sets simulated location (evidence: `README.md`)
- Developer or agent → Privacy settings: manages permissions (evidence: `README.md`)
- Developer or agent → Semantic navigation: finds UI elements (evidence: `README.md`)
- Semantic navigation → idb: interacts semantically (evidence: `README.md`)
- Developer or agent → Screen mapping: inspects screen (evidence: `README.md`)
- Developer or agent → Gestures and keyboard: performs gestures (evidence: `README.md`)
- Gestures and keyboard → idb: sends interaction (evidence: `README.md`)
- Semantic navigation → Simulator utilities: imports utilities (evidence: `ios-simulator-skill/skills/ios-simulator-skill/scripts/navigator.py`)
- Simulator utilities → Device helpers: exports device helpers (evidence: `ios-simulator-skill/skills/ios-simulator-skill/scripts/common/__init__.py`)
- Developer or agent → Accessibility audit: audits accessibility (evidence: `README.md`)
- Developer or agent → Localization audit: audits localization (evidence: `README.md`)
- Developer or agent → Visual comparison: compares screenshots (evidence: `README.md`)
- Developer or agent → App state capture: captures diagnostics (evidence: `README.md`)
- Developer or agent → Log monitoring: monitors logs (evidence: `README.md`)
- Developer or agent → Hang monitoring: monitors hangs (evidence: `README.md`)
- Hang monitoring → Hang analysis pipeline: filters and ranks (evidence: `ios-simulator-skill/skills/ios-simulator-skill/scripts/hang_watcher.py`)
- Hang monitoring → Hang session store: stores sessions (evidence: `ios-simulator-skill/skills/ios-simulator-skill/scripts/hang_watcher.py`)
- Developer or agent → App container inspection: inspects app data (evidence: `README.md`)
- App container inspection → Simulator utilities: imports utilities (evidence: `ios-simulator-skill/skills/ios-simulator-skill/scripts/container.py`)
- Developer or agent → Data model inspection: inspects data models (evidence: `README.md`)