debug-device-over-vusb

Debug on a Real Device over virtualUSB

Overview

Attach a real Kobiton device to the user's own machine over virtualUSB and debug the user's app on it the way they would with a phone on their desk: it shows up in adb devices (Android) or Xcode's device list (iOS), so the user's normal install / reproduce / read-the-logs loop works, driven from plain language. The skill owns the whole lifecycle - client install, device discovery, connect, verification, the debug loop, and an unconditional disconnect - and reports every failure as a plain-language meaning plus the next step.

Use it when the user wants to debug or reproduce a problem locally against a real device: "debug my app on a real Pixel", "make the device show up in adb", "get logcat from a real device while I reproduce this", "see the device in Xcode", "plug a Kobiton device into my machine", or any mention of "virtualUSB" / "vusb". For exploratory testing through Kobiton's own session CLI, route to run-interactive-session instead; for an agent-driven flow that should become a test case, drive-automation-session.

Prerequisites

Runs on macOS (any architecture) and Windows (x64 under Git Bash) and needs a persistent local filesystem - it runs a locally cached client binary, reads ~/.kobiton/.credentials, and hands device access to local adb / xcrun. Linux hosts are redirected by the preflight (outcome=redirected (limitation)): tell the user to use a macOS or Windows machine, or run-interactive-session for device access from Linux. See the Skill compatibility matrix in CLAUDE.md.

Before the flow can succeed:

• virtualUSB client - installed by this skill's own preflight (Step 1), never by the plugin's SessionStart hook or /automate:setup, so only users of this skill download it. The plugin pins one client build in skills/debug-device-over-vusb/VUSB_VERSION; the preflight fetches that build from https://public.kobiton.download/virtualusb/<version>/, verifies its published sha256, and on macOS caches the whole virtualUSB.app bundle under ~/.kobiton/vusb/<version>/. On Windows it caches the verified .msi and prints the install steps for the user (UAC, then vusb setup-adb in an administrator terminal). The wrapper ~/.kobiton/bin/vusb (symlink on macOS, exec-shim on Windows) resolves the binary by absolute path - ~/.kobiton/bin is not on PATH and must not be added.
• Credentials file - ~/.kobiton/.credentials with KOBITON_USER, KOBITON_API_KEY, KOBITON_PORTAL in the active profile ($KOBITON_PROFILE, default default), written by /automate:setup. ~/.kobiton/bin/vusb login reads it and signs the client in with the API key; the key never appears in the transcript.
• Kobiton MCP connection - listDevices({virtualUsb: true, …}) is how vUSB-ready devices are found. MCP tool names below are bare (listDevices); the host resolves its registered prefix.
• Local tooling - adb on PATH for Android; Xcode command line tools (xcrun devicectl) on macOS for iOS. On Windows, adb must be installed before the one-time vusb setup-adb, and an administrator terminal that runs as another account needs adb's folder added to its own PATH (the preflight's hand-off names it).
• Account and devices - an organization with the virtualUSB add-on and at least one private device whose host machine has virtualUSB enabled with reachable routing (virtual_usb_ready: true). Public cloud devices are never offered.
• Administrator approval once - on macOS the first connect (and every client version bump) installs the client's background daemon via a GUI administrator dialog; over SSH or without a GUI session this cannot complete. On Windows the .msi needs UAC.