awesome-ios-sim

简体中文 · MCP guide · DeepSeek Harness · Architecture

Simulator State as Code for iOS developers, CI pipelines, and AI agents.

awesome-ios-sim turns an iOS Simulator setup into a versioned profile that can be captured, diffed, planned, reviewed, and safely applied. It provides both a deterministic CLI and an MCP stdio server. It is also installable as a dsh-plugin bundle for DeepSeek Harness.

Project status: alpha. The state schema is v1alpha1. Review generated plans before applying them, especially plans containing erase or app removal operations.

Why this exists

Simulator automation is usually spread across shell scripts, undocumented defaults, and manual setup. That makes test environments difficult to reproduce and gives AI agents an unsafe, untyped shell surface.

This project introduces one workflow:

profile + current snapshot -> diff -> deterministic plan -> explicit confirmation -> audited apply

• Declarative: commit simulator profiles next to tests and application code.
• Reviewable: inspect the exact ordered operation plan before mutation.
• Agent-safe: MCP tools use JSON Schema and simulator_apply defaults to dry-run.
• Capability-aware: exact, best-effort, and unsupported state are reported explicitly.
• Public API only: mutations go through Apple's xcrun simctl; no private CoreSimulator frameworks.
• Local-first: no daemon, cloud account, telemetry, or API key.

Architecture

flowchart LR
    P[State profile] --> E[Pure Swift state engine]
    S[Live or saved snapshot] --> E
    E --> D[Diff]
    E --> PL[Ordered plan]
    PL --> C{Explicit confirm?}
    C -- No --> DR[Dry-run report]
    C -- Yes --> X[Typed simctl driver]
    X --> J[Execution receipts]
    CLI[CLI] --> E
    MCP[MCP stdio server] --> E

The state engine has no Xcode dependency and is tested with fixtures. Only SimctlDriver touches the host process boundary. The CLI and MCP server share the same planner, validation, and apply gates.

Requirements

• macOS 13 or later.
• Swift 6.
• Full Xcode with an iOS Simulator runtime for live inventory, snapshot, or apply operations.
• xcode-select configured to the intended Xcode installation.

Command Line Tools alone can build the package, but they do not provide CoreSimulator or simctl.

Install

git clone https://github.com/qubyyang/awesome-ios-sim.git
cd awesome-ios-sim
swift build -c release

The executables are produced at:

.build/release/ios-sim-state
.build/release/ios-sim-state-mcp

Homebrew distribution and signed release artifacts are planned after the schema stabilizes.

Quick start

List available simulators:

swift run ios-sim-state inventory

Capture one simulator:

swift run ios-sim-state snapshot --device <UDID> > simulator.snapshot.json

Generate an offline plan from the included example:

swift run ios-sim-state plan \
  --profile Examples/ui-tests.profile.json \
  --snapshot Examples/ui-tests.snapshot.json > simulator.plan.json

Preview apply behavior without mutation (the default):

swift run ios-sim-state apply --plan simulator.plan.json

Apply a reviewed plan and retain an execution journal:

swift run ios-sim-state apply \
  --plan simulator.plan.json \
  --confirm \
  --journal simulator.report.json

apply stops at the first failing operation. Each receipt contains the executed argument arrays, exit code, stdout, stderr, and timestamps.

State profile

Profiles are JSON documents validated against schemas/v1alpha1/simulator-state.schema.json. Fields with safe defaults may be omitted.

{
  "apiVersion": "awesome-ios-sim/v1alpha1",
  "kind": "SimulatorState",
  "metadata": { "name": "ui-tests" },
  "target": {
    "name": "iPhone 17 Pro",
    "runtime": "com.apple.CoreSimulator.SimRuntime.iOS-27-0"
  },
  "spec": {
    "power": "shutdown",
    "applications": [
      {
        "bundleIdentifier": "com.example.app",
        "sourcePath": "/absolute/path/to/Example.app",
        "running": true,
        "launchArguments": ["--uitesting"]
      }
    ],
    "preferences": [
      {
        "domain": "com.example.app",
        "key": "hasSeenOnboarding",
        "value": false
      }
    ],
    "statusBar": { "time": "09:41", "batteryLevel": 100 }
  }
}

power: "unchanged" restores the original power state after temporary work. When an erase is planned, a booted device is shut down first. Boot operations wait for simctl bootstatus -b before dependent work.

CLI

Command	Mutation	Purpose
inventory	No	List runtimes and simulators as stable JSON.
snapshot --device <UDID>	No	Capture managed state and capability metadata.
diff --profile <file> [--snapshot <file>]	No	Show desired/current differences.
plan --profile <file> [--snapshot <file> | --device <UDID>]	No	Produce an ordered operation plan.
apply --plan <file>	No	Return a dry-run report.
apply --plan <file> --confirm	Yes	Execute the reviewed plan serially.

All machine-facing output is JSON. Use --compact for one-line output.

MCP for AI agents

Build the MCP executable and point any stdio-capable MCP client at its absolute path:

{
  "mcpServers": {
    "awesome-ios-sim": {
      "command": "/absolute/path/awesome-ios-sim/.build/release/ios-sim-state-mcp"
    }
  }
}

The server exposes five tools:

Tool	Behavior
simulator_inventory	Read simulator inventory.
simulator_snapshot	Capture one simulator.
simulator_diff	Compare a profile with saved or live state.
simulator_plan	Generate a typed, ordered plan.
simulator_apply	Dry-run by default; mutates only with confirm: true.

The stdio server implements the MCP 2026-07-28 stateless request model, including server/discover, per-request _meta, cacheable tool lists, resultType, and JSON Schema 2020-12. It also accepts the legacy initialize handshake used by 2025-11-25, 2025-06-18, and 2024-11-05 tool clients. See the MCP guide for wire examples and the exact supported subset.

DeepSeek Harness plugin

Install the repository as a DSH bundle and start the Web profile:

dsh plugin --profile web add github:qubyyang/awesome-ios-sim
dsh web

Harness bridges the existing MCP server and exposes namespaced tools such as mcp__ios_sim__simulator_inventory and mcp__ios_sim__simulator_plan. The adapter is currently tested against @deepseek-ai/dsh 0.1.0-rc.7. Pin a tag or commit in reproducible environments because Harness is still in developer preview.

See the DeepSeek Harness guide for configuration, development, tool names, uninstall steps, and the host-process security boundary.

State coverage

State	Read	Write	Support
Power	Yes	Yes	Exact
Installed apps	Yes when listapps is available	Yes	Best effort
App running state	Not completely exposed by simctl	Launch/terminate	Best effort
Managed preference keys	No general readback	Scalar values and scalar arrays	Best effort
Status bar overrides	No complete readback	Yes, runtime-dependent	Best effort
Erase	N/A	Yes, explicit destructive operation	Exact mutation

The planner never silently upgrades best-effort data to exact state. Missing readback produces capability metadata, repeated idempotent writes, or a warning rather than a false claim of convergence.

Safety model

• No shell is invoked; executable and arguments are passed separately.
• diff, plan, and default apply cannot mutate a simulator.
• CLI apply requires --confirm; MCP apply requires boolean confirm: true.
• Operations are serialized and stop on first failure.
• A booted simulator is shut down before erase.
• Temporary boots restore the requested or original final power state.
• Tool schemas disallow unknown top-level arguments.
• No private framework loading, orphan-directory deletion, or filesystem cleanup is performed.

Treat plan files as executable intent. Review changes to target UDIDs, app paths, erase operations, and preference domains before confirmation.

Why Swift

Simulator work is dominated by Xcode and CoreSimulator process latency, not language-level CPU time. Swift provides native macOS distribution, strong Codable models, and direct alignment with iOS tooling without adding a runtime. Rust would be a strong choice for a portable, CPU-heavy indexer, but it would not materially accelerate simctl boot, install, or erase. The package keeps the pure state engine and process boundary separate so a specialized helper can be introduced later if profiling justifies it.

Development

swift build
swift test
npm ci
npm test
npm run pack:check
swift run ios-sim-state plan \
  --profile Examples/ui-tests.profile.json \
  --snapshot Examples/ui-tests.snapshot.json

See CONTRIBUTING.md, SECURITY.md, and the architecture notes. Please do not add private CoreSimulator APIs.

Roadmap

• Stabilize the profile schema and publish tagged binaries.
• Add Homebrew distribution and signed universal artifacts.
• Add reusable profile layers and presets.
• Expand capability-aware settings without private frameworks.
• Build a native SwiftUI companion app on top of the same state engine.

License

MIT. See LICENSE.