screen-debug.md

screen-debug.md

description
Capture and analyze the current Android device/emulator screen via ADB

Screen Debug: ADB Screen Capture & Analysis

You are tasked with capturing and analyzing what is currently displayed on a connected Android device or emulator. This helps debug UI issues, verify screen state, and inspect the view hierarchy.

User Context

$ARGUMENTS

Steps

Step 1: Check ADB connectivity

Run adb devices to verify a device/emulator is connected. If the output shows no devices (only the header line), inform the user that no device is connected and stop. If multiple devices are listed, note this but proceed with the default device.

Step 2: Capture screenshot

adb exec-out screencap -p > /tmp/android_screenshot.png

If the command fails, inform the user and stop.

Step 3: Capture UI hierarchy

adb exec-out uiautomator dump /dev/tty

Save the XML output for analysis. This command may fail on certain screens (e.g., splash screens, Flutter views, locked screens). If it fails, note this but continue with the screenshot and activity info.

Step 4: Get current activity and fragment info

adb shell "dumpsys activity activities | grep -E 'ResumedActivity|mFocused|topResumedActivity'"

This tells us which Activity is currently in the foreground.

Step 5: View and analyze the screenshot

Use the Read tool on /tmp/android_screenshot.png to visually inspect the screen. Claude Code is multimodal and can see images directly.

Step 6: Present findings

Combine all three data sources into a clear report:

1. Screenshot analysis: Describe what is visible on the screen - layout, text, buttons, images, states, errors, etc.
2. Current Activity: Report which Activity/Fragment is displayed based on the dumpsys output.
3. UI hierarchy details: If the uiautomator dump succeeded, extract key elements including:
   • Resource IDs (resource-id)
   • Text content (text)
   • Element bounds (bounds)
   • Clickable/focusable state
   • Any elements that appear relevant to the user's question

If the user provided context via $ARGUMENTS, focus the analysis on answering their specific question about the screen. Otherwise, provide a general overview of the screen state.

Important notes

• Always capture the screenshot first before any analysis
• Handle failures gracefully - if uiautomator fails, the screenshot + activity info are still valuable
• When reporting UI elements, include their resource-ids so the user can find them in code
• Keep the analysis focused and actionable - highlight what matters for debugging
• If the screen appears to show an error state, crash dialog, or ANR dialog, call this out prominently

Nice! Thanks for sharing, I'll try this one