# Introduction

Device automation for mobile apps, from a shell or an AI agent.

Karagöz drives an Android emulator, an Android phone, an iOS simulator or an iPhone, from your terminal or from an AI agent. Each command does one thing, like taking a screenshot or tapping a button, and answers with one line of JSON.

Early development. Not on npm yet: install it from source.

## How it works

You run a command and read one line back:

```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]}}
```

That line is the command’s result, and the exit code is `0`. When a command fails, the line is `{"error":{"code":"<CODE>","message":"<text>"}}` and the exit code is `1`. A program tells failures apart by `error.code`; the message is for people and can change.

The commands, their flags and their output are the same on all four targets. An AI agent gets them through `karagoz mcp`, an MCP server whose 15 tools return the line the CLI prints.

## Why Karagöz

`adb`, `simctl` and `devicectl` run the command; Karagöz tells you what the command actually did.

- **What happened, as a code.** `simctl` and `devicectl` report success for uninstalling an app that is not there. Karagöz checks first and returns `APP_NOT_FOUND`. A refused install is `INSTALL_FAILED`, with the platform’s own code in `reason`.
- **The accessibility tree first.** To see the screen, read `ui-tree` before taking a screenshot. The tree is text a program can search, costs a few hundred to a few thousand tokens, and gives the bounds needed to tap. A screenshot is saved to disk and returned as a path.
- **It installs only what you ask.** Nothing goes on a device by itself: `install` installs only the app you pass it, and `install-runner` only Karagöz’s runner.

## What it is not

- **Not a test framework.** No assertions, no test runner, no recorded flows, no retry policy, no reports. `tap --timeout` waits for a node to appear; it never repeats an action.
- **Not a design comparison tool.** Figma diffing, measurement and reporting belong a layer above. Karagöz produces the raw input and the metadata to measure it with, but does not interpret it.

## What do you want to do?

- [Get started](https://karagozmcp.com/docs/getting-started/): Install, check your setup, run your first commands
- [Check what a target needs](https://karagozmcp.com/docs/requirements/): Android, iOS simulator, iPhone
- [Install it](https://karagozmcp.com/docs/install/): From source, in 6 commands
- [Connect an AI agent](https://karagozmcp.com/docs/mcp/): Claude Code, Codex, Cursor, VS Code, Claude Desktop
- [Find a command](https://karagozmcp.com/docs/#commands): All 15, one page each
- [Look up an error code](https://karagozmcp.com/docs/error-codes/): What each code means and what returns it

## Commands

- [devices](https://karagozmcp.com/docs/commands/devices/): List connected devices
- [screenshot](https://karagozmcp.com/docs/commands/screenshot/): Save a full-resolution PNG and return its path with scale metadata
- [ui-tree](https://karagozmcp.com/docs/commands/ui-tree/): Return the accessibility tree of the focused window
- [tap](https://karagozmcp.com/docs/commands/tap/): Tap or long-press a point, or a node found by text or id
- [swipe](https://karagozmcp.com/docs/commands/swipe/): Swipe between two points
- [text](https://karagozmcp.com/docs/commands/text/): Type text into the focused field
- [key](https://karagozmcp.com/docs/commands/key/): Press a key
- [install](https://karagozmcp.com/docs/commands/install/): Install or replace an app
- [launch](https://karagozmcp.com/docs/commands/launch/): Start an app as its launcher icon does
- [terminate](https://karagozmcp.com/docs/commands/terminate/): Stop every process of an app
- [uninstall](https://karagozmcp.com/docs/commands/uninstall/): Remove an app
- [logs](https://karagozmcp.com/docs/commands/logs/): Read the device log
- [doctor](https://karagozmcp.com/docs/commands/doctor/): Report which adb and Xcode karagoz uses
- [install-runner](https://karagozmcp.com/docs/commands/install-runner/): Build karagoz's runner and install it on an iPhone
- [uninstall-runner](https://karagozmcp.com/docs/commands/uninstall-runner/): Remove karagoz's runner from an iPhone

Every command except `devices` and `doctor` works on one device. When more than one is listed, pick it with `--device <id or name>` or `KARAGOZ_DEVICE`: [Device selection](https://karagozmcp.com/docs/device-selection/). `karagoz mcp` starts the [MCP server](https://karagozmcp.com/docs/mcp/) on stdio.