---
name: agent-phone-use
description: Set up, repair, diagnose, and operate Agent Phone Use for one-click Windows control of Android phones or tablets over trusted local Wi-Fi using official scrcpy, Android Wireless debugging, ADB pairing, and mDNS discovery. Use when an agent should handle every Windows-side step while the user only enables Developer options/Wireless debugging and supplies the temporary six-digit code; also use for cable-free mirroring/control, no-terminal shortcuts, pairing recovery, dropped Wireless debugging, duplicate launches, changing IP addresses, ADB aliases, `_adb-tls-pairing._tcp`, `_adb-tls-connect._tcp`, scrcpy/Computer Use failures, or careful agent-driven phone UI actions.
---

# Agent Phone Use

Set up a local-only Windows-to-Android control path. Own the computer work; keep the phone owner's part minimal.

## Compatibility gate

- Proceed only for a Windows 10/11 computer and an Android 11+ phone or tablet.
- Stop before installation for iPhone/iPad (iOS/iPadOS) or a macOS/Linux computer. This release does not package or test those paths.
- Do not assume a manufacturer. Android menu labels and extra control permissions vary; use the actual device and observed error.

## Load the reference

Read [references/agent-runbook.md](references/agent-runbook.md) before installing, repairing, diagnosing, validating, or operating the phone through scrcpy.

## User interaction contract

- Ask the user only to use the same trusted Wi-Fi, enable Developer options and Wireless debugging, open **Pair device with pairing code**, provide the temporary six-digit code, and handle Android security prompts.
- Do not ask a non-technical user to download tools, open PowerShell, copy an IP/port, select an mDNS service, install the shortcut, or run tests.
- Communicate in the user's language. Keep setup instructions phone-only unless the user explicitly asks for manual computer steps.
- Ask for the pairing code only when the pairing service is ready. Treat it as temporary private data: do not echo, log, store, commit, or include it in the final response.

## Workflow

1. Enforce the compatibility gate, confirm the same trusted Wi-Fi, and confirm authorization to control the phone.
2. Inspect existing tools. Locate or install scrcpy only from `https://github.com/Genymobile/scrcpy` or WinGet package `Genymobile.scrcpy`.
3. Treat pairing and connection as separate services:
   - Use `_adb-tls-pairing._tcp` for one-time `adb pair`.
   - After pairing, use `_adb-tls-connect._tcp` for `adb connect` and scrcpy.
   - Never assume the pairing port equals the connection port.
4. When the user supplies the code, use process environment `APU_PAIRING_CODE` only in a non-interactive execution surface that does not persist shell history. The helper validates six digits, pipes it to ADB stdin, and does not put it in ADB arguments:

   ```powershell
   $env:APU_PAIRING_CODE = "<six-digit-code>"
   try {
       powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\scripts\pair-android-wireless.ps1"
   } finally {
       Remove-Item Env:APU_PAIRING_CODE -ErrorAction SilentlyContinue
   }
   ```

   In an interactive terminal, omit the environment variable and use input control to type at ADB's prompt so the code does not enter command history. The user may also type it personally.
5. Install or repair the no-terminal shortcut. The default name is `连接 Android 手机` on a Chinese Windows UI and `Connect Android Phone` on other Windows UI languages:

   ```powershell
   powershell.exe -NoProfile -ExecutionPolicy Bypass -File ".\scripts\install-shortcut.ps1"
   ```

   Pass `-ScrcpyDir "<official extracted folder>"` only when automatic discovery cannot find a manually extracted release.
6. Run `scripts/start-agent-phone-use.ps1 -SelfCheck -NoGui`.
7. Read back the merged Windows desktop (current-user and common desktop sources) and require exactly one current managed action shortcut, perform a real launch, and test duplicate launch. Refresh Explorer and verify visually after a rename or migration; a file existing is not proof.
8. Report completion without exposing the code, endpoint, device ID, or logs.
9. For Computer Use, re-observe after navigation/input delays and confirm account, recipient, composed text, and sent result.

## Safety rules

- Do not download scrcpy from mirrors, repack sites, or similarly named domains.
- Do not hardcode a phone IP address, ADB endpoint, or device serial into scripts or shortcuts.
- Do not expose the computer to public ADB ports, configure router port forwarding, or use untrusted/public Wi-Fi.
- Do not revoke authorizations, forget devices, reset Developer options, kill unrelated processes, or change firewall policy unless diagnosis specifically requires it and the user agrees.
- Do not claim this bypasses lock screens, biometrics, payment/banking controls, DRM, work profiles, or app security.
- When multiple connect services are discovered, stop and ask the user to leave wireless debugging enabled on only the intended device. Do not guess.
- Do not count `adb devices` rows as physical phones: one phone may expose both an endpoint and an mDNS transport alias. Select one `_adb-tls-connect._tcp` endpoint and use `adb -s <selected-endpoint>` for every device-specific ADB action.
- Treat outbound sends as consequential: confirm recipient and content at action time, then verify the sender-side result.

## Bundled scripts

- `scripts/start-agent-phone-use.ps1`: enforce one active control chain, discover the current `_adb-tls-connect._tcp` endpoint, connect, verify it with explicit `adb -s`, log on a best-effort basis, and start scrcpy.
- `scripts/pair-android-wireless.ps1`: locate official ADB, discover exactly one `_adb-tls-pairing._tcp` service, then accept the code from `APU_PAIRING_CODE` over stdin or fall back to ADB's interactive prompt.
- `scripts/start-hidden.vbs`: run the launcher through `wscript.exe` without a terminal window.
- `scripts/install-shortcut.ps1`: copy the launchers to `%LOCALAPPDATA%\AgentPhoneUse`, preserve conflicts outside the desktop, migrate recognized managed aliases, and create or repair one localized action shortcut.

Keep runtime logs and generated configuration outside the skill folder. Never commit logs, pairing codes, endpoints, device IDs, or machine-specific configuration.