adb-claw

# ADB Claw — Android Device Control

Control Android devices via the `adbclaw` CLI. Supports tap, swipe, type, screenshot, UI tree inspection, and app management through ADB.

## When to Use

- User asks to control, interact with, or automate an Android device
- User asks to test a mobile app or UI
- User mentions tapping, swiping, screenshots, or app launching on Android
- User wants to install, launch, or manage apps on a connected Android device

## When NOT to Use

- iOS devices — use peekaboo or other iOS tools
- Desktop UI automation — use peekaboo (macOS)
- ADB not available and user can't install it

## Setup

Requires two binaries:

1. **adbclaw** — the control CLI
2. **adb** — Android Debug Bridge (from Android SDK Platform-Tools)

The Android device must have **USB debugging enabled** and be connected via USB.

```bash
# Verify setup
adbclaw doctor
```

## Global Flags

| Flag | Short | Description | Default |
|------|-------|-------------|---------|
| `--serial` | `-s` | Target device serial (when multiple devices connected) | auto-detect |
| `--output` | `-o` | Output format: `json`, `text`, `quiet` | `json` |
| `--timeout` | | Command timeout in milliseconds | `30000` |
| `--verbose` | | Enable debug output to stderr | `false` |

## Commands

### observe — Screenshot + UI Tree (Primary Command)

Captures screenshot and UI element tree in one call. **Always use this before and after actions.**

```bash
adbclaw observe              # Default
adbclaw observe --width 540  # Scale screenshot width
```

Returns: base64 PNG screenshot, indexed UI elements with text/id/bounds/center coordinates.

### screenshot — Capture Screen

```bash
adbclaw screenshot                      # Returns base64 PNG in JSON
adbclaw screenshot -f output.png        # Save to file
adbclaw screenshot --width 540          # Scale down
```

### tap — Tap UI Element

Tap by element index (preferred), resource ID, text, or coordinates:

```bash
adbclaw tap --index 5            # Tap elem...