# Requirements

What each target needs, and where Karagöz looks for adb and Xcode.

## 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](https://karagozmcp.com/docs/requirements/#adb) 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](https://karagozmcp.com/docs/requirements/#cache-folder).
- 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`](https://karagozmcp.com/docs/error-codes/#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`](https://karagozmcp.com/docs/commands/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](https://karagozmcp.com/docs/commands/install-runner/#before-you-start) covers saving the team and free accounts.

## Check your setup

[`karagoz doctor`](https://karagozmcp.com/docs/commands/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:

```json
{
  "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."
  }
}
```

### 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.