/hz-vr-debug

name: hz-vr-debug
license: Apache-2.0
description: "Debugs Meta VR and Horizon OS VR, MR, and Android applications using the metavr CLI — view logs, capture screenshots, and diagnose common issues. Use when troubleshooting crashes, errors, or unexpected behavior on Meta VR devices. Build paths: All; use hz-quest-verify-first if the path is unclear."
allowed-tools: Bash(metavr:*), Bash(hzdb:*), Bash(npx:*)

VR Debug Skill

Debug Meta VR, MR, and Android applications using the `metavr` command-line interface. This skill covers viewing application logs, capturing device state, diagnosing crashes, and resolving common issues encountered during Meta VR development.

When to Use This Skill

Use this skill when you need to:

• Debug an application running on a connected Meta VR device
• View real-time or historical application logs (logcat)
• Capture screenshots of the VR/MR view
• Diagnose application crashes, rendering glitches, or performance problems
• Investigate tracking, controller, audio, or permission issues
• Pull diagnostic files from the device for offline analysis

This skill is relevant for Meta VR Glasses and Meta Quest headsets (Quest 2, Quest 3, Quest 3S, Quest Pro) running Horizon OS.

Prerequisites

Before using this skill, ensure the following are in place:

1. **metavr CLI installed** -- Install the standalone `metavr` CLI binary on your PATH (see the `metavr-cli` skill), or invoke it on demand via `npx` with no install:

   metavr --version

metavr wraps ADB and adds Meta VR-specific device management, log viewing, screenshot capture, and file management. Examples below use the bare `metavr` command. If `metavr` is not on PATH, invoke the same CLI via `npx -y metavr <args>` (published as the npm package `metavr`). 2. **Meta VR device connected via USB** -- Use a USB-C cable that supports data transfer (not charge-only). 3. **Developer mode enabled** -- Developer mode must be turned on in the Meta Horizon app on your phone, under your headset's settings. 4. **ADB authorization accepted** -- The first time you connect, you must put on the headset and accept the "Allow USB debugging" prompt.

Quick Start Workflow

The fastest way to begin debugging a Meta VR application:

# 1. Verify the device is connected and recognized
metavr device list

# 2. List applications currently installed
metavr app list

# 3. View live logs (most recent 100 lines)
metavr log

# 4. Capture a screenshot of the current VR view
metavr capture screenshot

If `metavr device list` returns no devices, check the USB cable, developer mode, and ADB authorization.

Key Debugging Commands

Device Commands

| Command | Description | | -------------------------- | ------------------------------------------------ | | `metavr device list` | List all connected Meta VR devices | | `metavr device info <id>` | Show device model, OS version, and more | | `metavr device battery` | Show battery level and charging status | | `metavr device wake` | Wake the device from sleep | | `metavr device reboot` | Reboot the device | | `metavr device connect <ip>` | Connect to a device over WiFi |

Log Commands

| Command | Description | | ------------------------------------ | ---------------------------------------------- | | `metavr log` | View the last 100 log lines | | `metavr log -n 500` | View the last 500 log lines | | `metavr log --tag Unity` | Filter logs by tag | | `metavr log --level E` | Filter by severity (V, D, I, W, E, F) | | `metavr adb logcat` | Full logcat with advanced filtering options | | `metavr adb logcat --follow` | Stream logs continuously |

Application Commands

| Command | Description | | -------------------------------- | ---------------------------------------------- | | `metavr app list` | List installed applications | | `metavr app info <package>` | Show detailed info about an app | | `metavr app launch <package>` | Launch an application by package name | | `metavr app stop <package>` | Force-stop a running application | | `metavr app clear <package>` | Clear application data and cache | | `metavr app install <apk>` | Install an APK to the device | | `metavr app uninstall <package>` | Uninstall an application |

Capture Commands

| Command | Description | | ------------------------------------ | -------------------------------------------------- | | `metavr capture screenshot` | Capture a screenshot of the current VR/MR view | | `metavr capture screenshot -o file.png`| Save screenshot to a specific file |

File Commands

| Command | Description | | ------------------------------------------------ | ---------------------------------------- | | `metavr files ls /sdcard/` | List files on the device | | `metavr files pull /sdcard/path/file ./local/` | Pull a file from the device | | `metavr files push ./local/file /sdcard/path/` | Push a file to the device | | `metavr files rm /sdcard/path/file` | Delete a file on the device | | `metavr files mkdir /sdcard/path/dir` | Create a director