SimDeck

SimDeck is a developer tool built for streamlining mobile app development for coding agents. Drive Simulator from the CLI using agents, browser, and automated tests on macOS.

---

Try it out

npx simdeck

Install the CLI globally for agentic-use:

npm i -g simdeck@latest

After installing the CLI, install the Codex skill so agents know the stable SimDeck workflow:

npx skills add NativeScript/SimDeck --skill simdeck -g

For VS Code, install the nativescript.simdeck-vscode extension to open the simulator view inside the editor.

Features

• Local simulator video stream over WebTransport or WebRTC, hardware-encoded in full resolution
• Full simulator control & inspection using private accessibility APIs
• CoreSimulator chrome asset rendering for device bezels
• NativeScript, React Native, UIKit and SwiftUI runtime inspector plugins to view app's view hierarchy live
• simdeck/test for fast JS/TS app tests that can query accessibility state and drive simulator controls.
• SimDeck Studio for automatic PR deployments to on-demand simulators

Documentation

Full documentation lives at simdeck.nativescript.org, with guides, the CLI reference, the REST API, the video pipeline, and the inspector protocols.

Quick start

simdeck

This starts a workspace-local foreground daemon, prints local and LAN HTTP URLs plus a pairing code for LAN browsers, and stops when you press q or Ctrl-C. To focus a specific simulator by name or UDID, pass it as the only argument:

simdeck "iPhone 17 Pro Max"

Use simdeck ui --open or simdeck daemon start when you want a reusable background daemon instead. The no-subcommand lifecycle shortcuts are simdeck -d for detached start, simdeck -k to kill the background daemon, and simdeck -r to restart it. The served loopback browser UI receives the generated API access token automatically. LAN browsers pair with the printed code before receiving the API cookie.

CLI commands automatically use the same warm daemon:

simdeck list
simdeck tap <udid> 0.5 0.5 --normalized
simdeck describe <udid> --format agent --max-depth 2

Daemon

Manage the project daemon explicitly when needed:

simdeck daemon start
simdeck daemon status
simdeck daemon stop

simdeck daemon manages the normal per-project warm process.

Use software H.264's low-latency profile on slower runners where freshness is more important than full-resolution smoothness:

simdeck daemon start --video-codec h264-software --low-latency

Restart the CoreSimulator service layer when simctl reports a stale service version or the live display gets stuck before the first frame:

simdeck core-simulator restart

You can also start or stop the CoreSimulator service layer explicitly:

simdeck core-simulator start
simdeck core-simulator shutdown

CLI

simdeck list
simdeck boot <udid>
simdeck shutdown <udid>
simdeck erase <udid>
simdeck install <udid> /path/to/App.app
simdeck uninstall <udid> com.example.App
simdeck open-url <udid> https://example.com
simdeck launch <udid> com.apple.Preferences
simdeck toggle-appearance <udid>
simdeck pasteboard set <udid> "hello"
simdeck pasteboard get <udid>
simdeck screenshot <udid> --output screen.png
simdeck describe <udid>
simdeck describe <udid> --format agent --max-depth 4
simdeck describe <udid> --point 120,240
simdeck tap <udid> 120 240
simdeck tap <udid> --label "Continue" --wait-timeout-ms 5000
simdeck swipe <udid> 200 700 200 200
simdeck gesture <udid> scroll-down
simdeck pinch <udid> --start-distance 160 --end-distance 80
simdeck rotate-gesture <udid> --radius 100 --degrees 90
simdeck touch <udid> 0.5 0.5 --phase began --normalized
simdeck touch <udid> 120 240 --down --up --delay-ms 800
simdeck key <udid> enter
simdeck key-sequence <udid> --keycodes h,e,l,l,o
simdeck key-combo <udid> --modifiers cmd --key a
simdeck type <udid> "hello"
simdeck type <udid> --file message.txt
simdeck button <udid> lock --duration-ms 1000
simdeck batch <udid> --step "tap --label Continue" --step "type 'hello'"
simdeck dismiss-keyboard <udid>
simdeck home <udid>
simdeck app-switcher <udid>
simdeck rotate-left <udid>
simdeck rotate-right <udid>
simdeck chrome-profile <udid>
simdeck logs <udid> --seconds 30 --limit 200

describe uses the project daemon to prefer React Native, NativeScript, or UIKit in-app inspectors, then falls back to the built-in private CoreSimulator accessibility bridge. Use --format agent or --format compact-json for lower-token hierarchy dumps. Coordinate commands accept screen coordinates from the accessibility tree by default; pass --normalized to send 0.0..1.0 coordinates directly.

JS/TS Tests

import { connect } from "simdeck/test";

const sim = await connect();
try {
  await sim.tap("<udid>", 0.5, 0.5);
  await sim.waitFor("<udid>", { label: "Continue" });
  await sim.screenshot("<udid>");
} finally {
  sim.close();
}

connect() starts the project daemon when needed, reuses it when it is already healthy, and only stops daemons it started itself.

NativeScript Inspector

NativeScript apps can connect directly to the running server from JS and expose their NativeScript logical hierarchy plus raw UIKit backing views without linking the Swift inspector framework:

import { startSimDeckInspector } from "@nativescript/simdeck-inspector";

if (__DEV__) {
  startSimDeckInspector({ port: 4310 });
}

The runtime connects to GET /api/inspector/connect as a WebSocket. The Rust server prefers connected NativeScript inspectors for hierarchy requests and falls back to the Swift TCP inspector or the built-in native accessibility bridge when no matching app inspector is available.

React Native Inspector

React Native apps can expose their component tree and Metro dev-mode source locations with the React Native inspector package:

import { AppRegistry } from "react-native";
import { startSimDeckReactNativeInspector } from "react-native-simdeck";
import App from "./App";

if (__DEV__) {
  startSimDeckReactNativeInspector({ port: 4310 });
}

AppRegistry.registerComponent("Example", () => App);

Call it before AppRegistry.registerComponent(...) so the package can capture React Fiber commits.

VS Code

Install the nativescript.simdeck extension from the VS Code Marketplace, then run SimDeck: Open Simulator View from the Command Palette. The extension opens the simulator inside a VS Code panel and auto-starts the local daemon when it is not already reachable.

Contributing

Contributors should read CONTRIBUTING.md for local build instructions, the dev workflow, and architecture notes.

Copyright notice

Copyright OpenJS Foundation and NativeScript contributors. All rights reserved. The OpenJS Foundation has registered trademarks and uses trademarks. For a list of trademarks of the OpenJS Foundation, please see our Trademark Policy and Trademark List. Trademarks and logos not indicated on the list of OpenJS Foundation trademarks are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.

The OpenJS Foundation | Terms of Use | Privacy Policy | OpenJS Foundation Bylaws | Trademark Policy | Trademark List | Cookie Policy

Made with ❤️