adb

name	adb
description	Manipulates Android devices via ADB with emphasis on Wear OS. Provides scripts for screenshots, screen recording, tile management, WearableService inspection, package operations, and device configuration. Use when working with adb, Android devices, Wear OS watches, tiles, wearable data layer, dumpsys, or device debugging. Triggers: adb, android device, wear os, wearable, tile, screenshot, screen recording, dumpsys, logcat.
compatibility	Requires adb. Some scripts require magick (ImageMagick), scrcpy, ffmpeg, or jq. Designed for filesystem-based agents with bash access.

Android ADB

Important: Use Scripts First

ALWAYS prefer the scripts in scripts/ over raw adb commands. Scripts are located in the scripts/ subdirectory of this skill's folder. References to scripts/... in this skill are relative to this skill directory. They provide features that raw commands do not, such as:

• Automatic circular masking for Wear OS screenshots
• Device wake-up before capture
• Clipboard integration on macOS
• Sensible default filenames and error handling

When to read the script source: If a script doesn't do exactly what you need, or fails due to missing dependencies, read the script source. The scripts encode solutions to edge cases and platform quirks that may not be obvious—use them as reference when building similar functionality.

Quick Start

Target specific devices using the ANDROID_SERIAL environment variable if multiple devices are connected.

Highest-Value Commands

• Screenshot (auto-masks circular Wear OS displays): scripts/adb-screenshot

• Wear OS Tile Debugging Workflow: scripts/adb-tile-add com.example/.MyTileService -> output gives INDEX scripts/adb-tile-switch INDEX

• Inspect Wear OS Data Layer: adb exec-out dumpsys activity service WearableService

• Package Information: scripts/packagename tiles PACKAGE_NAME scripts/packagename services PACKAGE_NAME

• Device Info: scripts/adb-device-properties

• Discover Activities: scripts/adb-activities (find launcher, TV, settings activities)

Script Index

See references/command-index.md for detailed usage.

Device Basics

• scripts/adb-device-properties: Show key device properties (model, manufacturer, API level, display size, etc.).
• scripts/adb-log: Write a message to the system log.

For simple one-shot operations (listing device serials, waking or sleeping the device, filtering logcat by tag, sending VIEW intents, toggling "Show touches"), use raw adb commands. See references/command-index.md for the exact invocations, including non-obvious flags.

Media Capture

• scripts/adb-screenshot: Take a screenshot. Always use this instead of raw adb shell screencap. Features: auto-detects square Wear OS displays and applies circular mask, wakes device before capture, copies to macOS clipboard, generates timestamped filenames by default.
• scripts/adb-screenrecord: Record the screen to a file. Automatically detects devices that require raw frame streaming (e.g., Samsung Wear OS watches) and uses ffmpeg for capture, while defaulting to scrcpy for standard devices.

Tile Management (Wear OS)

• scripts/adb-tile-add: Add a tile component for debugging.
• scripts/adb-tile-switch: Switch the active tile.
• scripts/adb-tile-remove: Remove a tile.
• scripts/adb-tiles: List available tiles and indicate which are in the carousel.
• scripts/adb-watchface-set: Set the current watch face.

[!NOTE] Tile Indexing (Index=[0]): When adding a new tile using scripts/adb-tile-add, the output often indicates Index=[0]. This means the tile was added to the first position in the carousel, pushing existing tiles down. It does not mean it has overwritten previous tiles.

Verifying Installed Tiles: Use scripts/adb-tiles to list all available tiles and see which ones are currently in the carousel. The output uses prefixes like UTWC where C indicates it is in the carousel.

Activity Discovery

• scripts/adb-activities: List activities tagged by category (Launcher, Home, TV/Leanback, Settings). Use --launcher-only, --tv-only, --settings-only to filter. Add --all to include system apps.
• scripts/adb-uihierarchy: Dump the UI hierarchy to an XML file.
• scripts/adb-currentfocus: Display the package name that currently has focus.

Package Operations

• scripts/packagename: Comprehensive package tool (uninstall, launch, stop, clear-cache, logcat, jobscheduler).
• scripts/adb-packages: List installed packages.

System & Dumpsys

• scripts/adb-battery-stats: Display battery-related information and settings.

Display & Demo Mode

• scripts/adb-demo: Toggle Android demo mode (on / off): clean status bar, fixed clock, show touches, long screen timeout.
• scripts/adb-fontscale: Get or set the system font scale (get / set default|large|NUMBER).
• scripts/adb-theme: Get or set system theme customization (e.g., set to 'lemongrass'). Requires Wear OS 6+ (API 36+).
• scripts/adb-settings-theme: Open system theme settings (requires root/debuggable build).

Safety Notes

• Debug Broadcasts: Tile management relies on Wear OS debug broadcasts (com.google.android.wearable.app.DEBUG_SURFACE) which may not work on production builds without developer options or specific system images.
• USB Debugging: Requires adb authorization.
• Destructive Actions: Scripts like adb-tile-remove or packagename uninstall modify device state.

Reference Material

• Command Reference: Detailed usage and arguments for all scripts. See references/command-index.md.
• Troubleshooting: Solutions for connection issues, missing dependencies, and Wear OS quirks. See references/troubleshooting.md.