# Android Adb Connect

> Android Adb Connect is an Agent Skill for apps & automation published in the meain/dotfiles repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Connect to an Android phone over ADB wireless (Galaxy S25 at meain's setup), install/launch APKs, take screenshots, and drive the UI via uiautomator. Triggers: "connect to phone", "adb connect", "test on phone", "screenshot the phone", "install on phone", "phone is at 192.168.1.3", any task that needs to drive an Android device from the host.

- Skill name: `android-adb-connect`
- Category: [Apps & Automation](https://www.openparable.com/skill/apps-automation/1)
- Source: https://github.com/meain/dotfiles/blob/HEAD/agents/.agents/skills/android-adb-connect/SKILL.md
- Repository: meain/dotfiles (282 GitHub stars when collected)

## SKILL.md

# Connect to Android phone over ADB wireless

This skill captures the actual quirks of meain's setup. The phone is a **Samsung Galaxy S25** on the same WiFi as the host. The ADB SDK lives at `~/Android/sdk-edo` (not the system path) — always `export ANDROID_HOME=$HOME/Android/sdk-edo` before running `adb`.

## When to use

- The user says "connect to the phone", "test on phone", "adb connect …"
- They paste a `host:port` and optionally a 6-digit pairing code
- You need to install an APK on the device, drive the UI, or screenshot it
- A previous connection dropped (port rotates every time wireless debugging is toggled)

## Step 1 — set up the environment

```bash
export ANDROID_HOME=$HOME/Android/sdk-edo
# Java is only needed for builds, not for adb itself
export PATH=$ANDROID_HOME/platform-tools:$PATH

adb devices   # check what's already attached
```

If `adb` isn't found, the SDK is at `~/Android/sdk-edo/platform-tools/adb`.

If any entry shows status `device`, check if it's the Galaxy S25 before proceeding to connect:

```bash
adb -s <device-id> shell getprop ro.product.model
# SM-S938B → it's the Galaxy S25, use this device ID and skip Step 2 entirely
```

Use that ID with `-s` for all subsequent commands.

## Step 2 — connect

### Already paired (the common case)

The phone remembers the pairing across reboots, but the **wireless port changes** every time Wireless Debugging is toggled. The user will typically paste a new `host:port` — use it directly:

```bash
adb connect 192.168.1.3:38181
```

If that fails with `failed to authenticate` or hangs, the pairing has expired — go to Step 2b.

### First-time or expired pairing

The user needs to open **Settings → Developer options → Wireless debugging → Pair device with pairing code** on the phone. That screen shows a `host:pairing_port` and a 6-digit code. They are *separate* from the regular `host:port` shown on the main Wireless debugging screen.

```bash
adb pair 192.168.1.3:40319        # pairing port from the phone (different from connect port)
# adb prompts for the code; or pass it inline:
adb pair 192.168.1.3:40319 657538
```

Then connect using the regular (non-pairing) port shown on the main Wireless debugging screen:

```bash
adb connect 192.168.1.3:38181
```

### Discovering the port

If the user can't read the port off the phone, try mDNS:

```bash
adb mdns services
```

It lists `adb-tls-pairing` and `adb-tls-connect` entries with their ports. The pairing entry rotates each time the pairing code screen is opened.

### TLS failures

`SSLV3_ALERT_CERTIFICATE_UNKNOWN` or "TLS handshake failed" means the host and phone disagree on the pairing — re-pair from scratch via Step 2b. Don't retry the same `adb connect` in a loop.

## Step 3 — verify and identify

```bash
adb devices
# Should show e.g. 192.168.1.3:38181  device
```

Always pass `-s <host:port>` to subsequent commands when more than one device is listed (the `adb-RZGY...` mDNS entry can show up alongside the IP one).

## Step 4 — common operations

### Install / launch an app

```bash
adb -s 192.168.1.3:38181 install -r app/build/outputs/apk/debug/app-debug.apk
adb -s 192.168.1.3:38181 shell am force-stop com.example.app
adb -s 192.168.1.3:38181 shell am start -n com.example.app/.MainActivity
```

### Screenshot

```bash
adb -s 192.168.1.3:38181 exec-out screencap -p > /tmp/phone.png
# Read it with the Read tool. If the API rejects large images, resize:
# sips -z 1200 555 /tmp/phone.png --out /tmp/phone_small.png
```

### Drive the UI (taps, text)

Coordinates are in the **device's native resolution** (1080×2340 on the S25). Don't scale to display size. Get exact bounds via:

```bash
adb -s 192.168.1.3:38181 shell uiautomator dump /sdcard/window.xml >/dev/null
adb -s 192.168.1.3:38181 shell cat /sdcard/window.xml \
  | tr '>' '\n' \
  | grep -oE '(text|content-desc|bounds)="[^"]+'
```

Then tap the center of `bounds="[x1,y1][x2,y2]"`:

```bash
adb -s 192.168.1.3:38181 shell input tap 540 1200
adb -s 192.168.1.3:38181 shell input text "hello%sworld"   # %s for spaces
adb -s 192.168.1.3:38181 shell input keyevent KEYCODE_BACK
adb -s 192.168.1.3:38181 shell input keyevent KEYCODE_WAKEUP
```

Quirks of `input text`:
- Spaces must be `%s`, not literal spaces.
- Avoid `!` — zsh history expansion can trigger before the command reaches the device.
- Newlines aren't supported; use `KEYCODE_ENTER` separately.

### Keep screen awake during testing

```bash
adb -s 192.168.1.3:38181 shell svc power stayon true    # USB or AC
# Always turn it back off when done:
adb -s 192.168.1.3:38181 shell svc power stayon false
```

### Logs

```bash
adb -s 192.168.1.3:38181 logcat -d -t 300 | grep com.example.app
```

### Pulling the app database (Room WAL gotcha)

`adb pull` of just the `.db` file is incomplete because Room uses WAL mode. Force-stop the app first to flush, then pull all three files:

```bash
adb -s 192.168.1.3:38181 shell am force-stop com.example.app
for f in app.db app.db-wal app.db-shm; do
  adb -s 192.168.1.3:38181 shell "run-as com.example.app cat databases/$f 2>/dev/null" > /tmp/$f
done
sqlite3 /tmp/app.db "SELECT ..."
```

The device's `sqlite3` binary is missing on stock Samsung — always pull and query locally.

## Project context

For the Edo project at `/Users/meain/dev/src/edo`, see its `CLAUDE.md` for the install/launch/screenshot pattern with the actual package name (`com.edo.app`).

---

Source: https://www.openparable.com/skill/apps-automation/android-adb-connect (OpenParable). Cite the canonical URL above.
