Requirements

All targets

• Node 22 or newer.
• Every command runs on all four targets, except install-runner and uninstall-runner, which run only on iPhones.
• Windows and Linux have not been run.

Android emulator and phone

• adb from Android platform-tools. Karagöz does not bundle it; Lookup and files lists where it looks.
• For install: platform-tools 30.0.0 or newer.
• A running emulator (emulator -avd <name>), or a phone with USB debugging on, in state device.
• For ui-tree and tap --text / --id: the screen on, and no other UiAutomation client connected (Appium, Maestro, uiautomator events).
• For input to reach apps: the screen unlocked.

iOS simulator (macOS)

• Xcode, opened once. The Command Line Tools alone have no simctl, and no swiftc for the helper.
• A booted simulator (on Xcode 27, xcrun simctl boot <name>; on older ones, open -a Simulator).
• For tap, swipe and key: Xcode 27 or newer. Older ones return NOT_SUPPORTED.
• For text: with Xcode 27 or newer, a simulator on iOS 27 or newer; an older one returns NOT_SUPPORTED. No UI test running on the same simulator.

iPhone (macOS)

• An iPhone connected to the Mac, and Xcode 15 or newer. The Command Line Tools alone have no devicectl.
• For screenshot: Xcode 27 or newer, opened once.
• For screenshot, install, launch, terminate and uninstall: paired with the Mac, and Developer Mode on (Settings > Privacy & Security > Developer Mode).
• For logs: paired, and connected by USB cable.
• For ui-tree, tap, swipe, text and key: paired, Developer Mode on, connected by USB cable, Settings > Developer > Enable UI Automation on, and Karagöz’s runner installed with install-runner.
• For install-runner: an Apple ID signed in to Xcode > Settings > Accounts whose team Xcode has saved, or --team. Its Before you start covers saving the team and free accounts.

Check your setup

karagoz doctor shows which adb Karagöz uses and why. On macOS it also shows the Xcode the simulator commands use, and what to fix.

Lookup and files

adb

Karagöz looks for adb on every run, in this order:

1. $ANDROID_HOME/platform-tools/adb
2. $ANDROID_SDK_ROOT/platform-tools/adb
3. adb on PATH
4. Android Studio’s default SDK: ~/Library/Android/sdk on macOS, ~/Android/Sdk on Linux, %LOCALAPPDATA%\Android\Sdk on Windows

• An empty variable is skipped.
• The first adb that starts is used for the rest of the run, so a broken adb under ANDROID_HOME does not fall back to PATH.
• An adb that fails to start with ENOENT (a missing interpreter or a broken link) counts as not there, and the next one is tried.

When none is found:

{
  "error": {
    "code": "ADB_NOT_FOUND",
    "message": "adb not found (tried ..., PATH). Install platform-tools (brew install --cask android-platform-tools, or download https://developer.android.com/tools/releases/platform-tools and add it to PATH) or set ANDROID_HOME to your Android SDK."
  }
}

Copy

simctl and devicectl

Karagöz runs CoreSimulator’s own simctl (/Library/Developer/PrivateFrameworks/CoreSimulator.framework/Versions/A/Resources/bin/simctl) and CoreDevice’s own devicectl (/Library/Developer/PrivateFrameworks/CoreDevice.framework/Versions/A/Resources/bin/devicectl). When DEVELOPER_DIR is set, it runs $DEVELOPER_DIR/usr/bin/simctl and $DEVELOPER_DIR/usr/bin/devicectl instead.

Cache folder

The first ui-tree, tap, swipe, text or key on a simulator compiles a small helper into ~/Library/Caches/karagoz/. It uses the selected Xcode’s swiftc: DEVELOPER_DIR, else the xcode-select one, else /Applications/Xcode.app. That takes a few seconds and happens again after an Xcode update. The helper’s folder is safe to delete.

The runner/ folder next to it holds Karagöz’s iPhone runner. After deleting it, run install-runner again.