awesome-ios-sim

简体中文 · [MCP guide](docs/MCP.md) · [DeepSeek Harness](docs/DEEPSEEK_HARNESS.md) · [Architecture](docs/ARCHITECTURE.md)

  

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

Checksummed native archives for Apple Silicon and Intel macOS are published on the Releases page. These initial archives are not yet code-signed or notarized. Homebrew distribution and signed universal artifacts are the next distribution stage.

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](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. Profile decoding is strict: unknown fields and empty identifiers are rejected. statusBar accepts only the public simctl status_bar overrides and validates enum values and numeric ranges before planning.

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:

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](docs/MCP.md) 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](docs/DEEPSEEK_HARNESS.md) for configuration, development, tool names, uninstall steps, and the host-process security boundary.

State coverage

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

Run the opt-in live suite against a real Xcode Simulator runtime:

DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
  Scripts/live-integration-test.sh

It creates and exclusively targets a uniquely named temporary simulator, verifies the CLI and MCP paths, checks dry-run safety and confirmed reconciliation, then deletes that exact device. Existing simulators are not selected or modified. The script requires jq; artifacts are retained under .build/live-integration/.

Build and inspect a versioned native release archive locally:

Scripts/release/verify-version.sh
Scripts/release/build-artifact.sh

GitHub automation can run an unpublished release candidate from the default branch. Tag-driven runs build separate arm64 and x86_64 archives, verify SHA-256 checksums, and publish provenance attestations. See the [compatibility contract](docs/COMPATIBILITY.md) and bilingual [release process](docs/RELEASING.md). No release is created from an untagged branch build.

See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and the [architecture notes](docs/ARCHITECTURE.md). Please do not add private CoreSimulator APIs.

Roadmap

• 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](LICENSE).