Karagöz
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
karagoz drives Android emulators and phones, and iOS simulators and iPhones on macOS. To see the screen, call ui_tree first: node bounds are the pixels tap and swipe take; take a screenshot only when you need the image. Pass device only when more than one device is connected. Each result is one JSON object; on failure, branch on error.code. If adb or Xcode is missing, old or broken, call doctor.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| devicesA | List Android devices and emulators, running iOS simulators, and iPhones connected to this Mac. |
| screenshotA | Save a full-resolution PNG of the screen and return its path with size, scale and safe area. Use ui_tree to read the screen; inline only to look at the image. |
| ui_treeA | Return the focused window's accessibility tree as JSON, compact by default: nodes with no text, label or action and nodes off screen are left out. Node bounds [left, top, right, bottom] are the physical pixels tap and swipe take. On an iPhone it needs karagoz's runner: install it once with install_runner. |
| tapA | Tap x, y in physical pixels, or the center of the node whose text or contentDesc (iOS: label or value) equals text, or whose resource id (iOS: identifier) matches id. An iPhone needs install_runner once. |
| long_pressA | Long-press x, y in physical pixels, or the center of the node whose text or contentDesc (iOS: label or value) equals text, or whose resource id (iOS: identifier) matches id. An iPhone needs install_runner once. |
| double_tapA | Double-tap x, y in physical pixels, or the center of the node whose text or contentDesc (iOS: label or value) equals text, or whose resource id (iOS: identifier) matches id. An iPhone needs install_runner once. |
| swipeA | Swipe from x1, y1 to x2, y2 in physical pixels. An iPhone needs install_runner once. |
| textA | Type into the focused field. Any text; on Android, text beyond ASCII is pasted through the clipboard and the old clip put back. An iPhone needs install_runner once. |
| keyB | Press one key. |
| installA | Install an .apk, or a .app or .ipa on an iOS simulator or iPhone, or replace the installed version of the same app. An iPhone takes only a build signed for it; karagoz does not re-sign. Times out after 30 s plus 1 s per MB. |
| launchA | Start an app as its launcher icon does. On iOS it returns before the app is in front. |
| open_urlA | Open a URL in the app that handles it, or in the app named by app. On iOS it returns before the app is in front, and a simulator may first ask "Open in ?". |
| terminateB | Force-stop every process of an app. |
| uninstallC | Remove an app. |
| logsA | Read the newest device log records, oldest first. On iOS without since: the last minute, or the last hour with package. An iPhone read takes about 10 s. |
| doctorA | Report which adb and Xcode tools karagoz uses, their versions, and how to fix one that is missing, old or broken. |
| install_runnerA | Build karagoz's runner with your Apple team and install it on a paired iPhone over USB; ui_tree, tap, swipe, text and key need it there. |
| uninstall_runnerB | Remove karagoz's runner and its provisioning profile from an iPhone. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 18 tools
Most tools have a clearly distinct purpose: device discovery, screenshots, UI inspection, gestures, app lifecycle, logs, and setup are separated. The only plausible overlaps are install/uninstall versus install_runner/uninstall_runner and launch versus open_url, but their descriptions make the target objects clear.
All tool names use lower_snake_case, making the set predictable to read. However, naming mixes bare imperative verbs (tap, swipe, install, launch) with noun/resource names (devices, screenshot, ui_tree, doctor, logs), so it is not a uniform verb_noun convention.
18 tools is slightly above the typical 3-15 range, but each maps to a real mobile automation need. Cross-platform device setup, runner management, UI interaction, and app lifecycle operations justify the size without obvious filler.
The surface covers device discovery, UI inspection, gestures, text/key input, app install/uninstall/launch/terminate, logs, and setup. Minor gaps exist for multi-touch gestures, hardware button shortcuts beyond key, and explicit waits, but agents can generally work around them.