Getting started

The steps below use an Android emulator. The commands and their output are the same on the other targets; 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 shows, then come back here.

3. Check your setup

~/app

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

Copy

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.

4. Find your device

~/app

$ karagoz devices
{"devices":[{"id":"emulator-5554","platform":"android","kind":"emulator","state":"device","name":"Medium_Phone_API_36.1"}]}exit 0

Copy

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.

For more information, see devices.

5. Read the screen

~/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":[…]}}

Copy

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:

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

Copy

For more information, see ui-tree.

6. Tap it

~/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]}}exit 0

Copy

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.

7. Go home and take a screenshot

~/app

$ karagoz key HOME
{"device":"emulator-5554","key":"KEYCODE_HOME","code":3}exit 0
$ 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}exit 0

Copy

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

For more information, see key and screenshot.

8. When a command fails

A failure prints an error line and exits 1:

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

Copy

Branch on error.code, not on the message: messages are for people and can change. 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 has the setup for Claude Code, Codex, Cursor, VS Code, Claude Desktop.