# Getting started

Build Karagöz, check your setup, and drive an Android emulator from the terminal.

The steps below use an Android emulator. The commands and their output are the same on the other targets; [Requirements](https://karagozmcp.com/docs/requirements/) lists what each one needs.

## 1. Before you start

- Node 22 or newer.
- `adb` from Android platform-tools.
- A running emulator: `emulator -avd <name>`.

## 2. Install Karagöz

Karagöz is not on npm yet. Build it from source and put `karagoz` on your `PATH` as [Install](https://karagozmcp.com/docs/install/) shows, then come back here.

## 3. Check your setup

```console title="~/app"
$ karagoz doctor
{"adb":{"status":"ok","source":"PATH","path":"/opt/homebrew/bin/adb","version":"37.0.0-14910828","candidates":[…]},"xcode":{"status":"ok",…}}
```

`doctor` exits `0` even when something is missing, so read the status. `adb.status` is `ok` when Karagöz found platform-tools 30.0.0 or newer; otherwise `adb.install` says how to install them. `xcode` is there on macOS only.

For more information, see [`doctor`](https://karagozmcp.com/docs/commands/doctor/).

## 4. Find your device

```console title="~/app"
$ karagoz devices
{"devices":[{"id":"emulator-5554","platform":"android","kind":"emulator","state":"device","name":"Medium_Phone_API_36.1"}]}
```

Only a device in state `device` can be used. When more than one is listed, pick one with `--device <id or name>` or `KARAGOZ_DEVICE`: [Device selection](https://karagozmcp.com/docs/device-selection/).

For more information, see [`devices`](https://karagozmcp.com/docs/commands/devices/).

## 5. Read the screen

```console title="~/app"
$ karagoz ui-tree
{"device":"emulator-5554","rotation":0,"root":{"class":"android.widget.FrameLayout","package":"com.google.android.apps.nexuslauncher","bounds":[0,0,1080,2400],"children":[…]}}
```

`ui-tree` prints the screen’s accessibility tree. Each node carries its text and its `bounds`, in screen pixels from the top left. On the launcher’s home screen, the Chrome icon is this node:

```json
{
  "class": "android.widget.TextView",
  "text": "Chrome",
  "contentDesc": "Chrome",
  "clickable": true,
  "longClickable": true,
  "focusable": true,
  "bounds": [581, 1905, 754, 2100]
}
```

For more information, see [`ui-tree`](https://karagozmcp.com/docs/commands/ui-tree/).

## 6. Tap it

```console title="~/app"
$ karagoz tap --text Chrome
{"device":"emulator-5554","x":667.5,"y":2002.5,"element":{"class":"android.widget.TextView","text":"Chrome","contentDesc":"Chrome","clickable":true,"longClickable":true,"focusable":true,"bounds":[581,1905,754,2100]}}
```

`tap --text` found the node in the tree and tapped its center, `(667.5, 2002.5)`. Exit `0` means Android accepted the event, not that the app reacted to it. Read the tree again to check.

For more information, see [`tap`](https://karagozmcp.com/docs/commands/tap/).

## 7. Go home and take a screenshot

```console title="~/app"
$ karagoz key HOME
{"device":"emulator-5554","key":"KEYCODE_HOME","code":3}
$ karagoz screenshot --out home.png
{"path":"/Users/me/home.png","device":"emulator-5554","pixels":{"width":1080,"height":2400},"logical":{"width":411.42857142857144,"height":914.2857142857143},"scale":2.625,"safeArea":{"top":63,"right":0,"bottom":63,"left":0},"rotation":0}
```

`screenshot` saved a full-resolution PNG and returned its path. The image never goes to the terminal.

For more information, see [`key`](https://karagozmcp.com/docs/commands/key/) and [`screenshot`](https://karagozmcp.com/docs/commands/screenshot/).

## 8. When a command fails

A failure prints an error line and exits `1`:

```json
{
  "error": {
    "code": "DEVICE_NOT_FOUND",
    "message": "device 'nosuch' from --device matches no device id or name. Listed: emulator-5554 (Medium_Phone_API_36.1)."
  }
}
```

Branch on `error.code`, not on the message: messages are for people and can change. [Error codes](https://karagozmcp.com/docs/error-codes/) lists every code.

## 9. Connect an AI agent

`karagoz mcp` serves the same commands to an AI agent as an MCP server, and each tool returns the line the CLI prints. [MCP server](https://karagozmcp.com/docs/mcp/) has the setup for Claude Code, Codex, Cursor, VS Code, Claude Desktop.