/hz-vr-debug

name: hz-vr-debug
license: Apache-2.0
description: Debugs Meta Quest and Horizon OS VR/MR applications using the metavr CLI — view logs, capture screenshots, diagnose common issues. Use when troubleshooting crashes, errors, or unexpected behavior on Quest devices.
allowed-tools: Bash(metavr:*) Bash(hzdb:*) Bash(npx:*)

VR Debug Skill

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

When to Use This Skill

Use this skill when you need to:

• Debug an application running on a connected Meta Quest 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 any Meta Quest headset (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 ready via `npx`** -- The `metavr` CLI is invoked on demand; no global install required:

   npx -y metavr --version

metavr wraps ADB and adds Quest-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 `@meta-quest/metavr`). 2. **Meta Quest 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 Quest 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 Quest 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 directory on the device |

Common Debugging Workflow

A typical debugging session follows this pattern:

1. Connect and Verify

metavr de