Agent Device DevTools for VS Code

Author, run, and inspect agent-device .ad scripts inside VS Code — Vitest-style.

Features

Authoring

• Syntax highlighting for .ad files — every agent-device 0.21 command (including gesture, orientation, hover, longpress, settings, tv-remote, diff, network, perf areas), @eN and versioned @eN~sM refs, flags, double-quoted strings, ${VAR} interpolation, # comments
• Completion for commands, first-positional forms (gesture pan, is visible, wait absent, record start, settings wifi, perf frames, …), command-scoped flags (--settle, --pointer-count, --surface, …), context keys (platform=, target=, timeout=, retries=), find locators and actions
• Variable completion inside ${...} — built-in AD_* plus env-defined names from the same file
• Header validation — context platform= accepts ios, android, macos, linux, harmonyos, vega, apple (and errors on web, which replay does not target); context target= accepts mobile / tv / desktop; timeout= and retries= (0-3) are range-checked; duplicate keys and context / env lines after the first action are flagged the same way agent-device rejects them. --platform / --target flag values get the same completion and checks
• Hover docs for commands, aliases (tap, long-press, launch), directives, and flags; hovering a removed command (rotate, metrics) names its replacement
• Gesture diagnostics + quick fixes — swipe, gesture pan/fling/drag/pinch/rotate/transform/swipe lines are checked against the agent-device 0.20 arity table. The retired trailing durationMs (swipe, fling, gesture swipe) and velocity (rotate) positionals are flagged as deprecated with a one-click fix that applies the same migration agent-device prints; swipe … <ms> additionally offers "convert to gesture pan" to keep the timing
• Selector language — label=, id=, text=, role=, value=, appname=, windowtitle= keys, boolean terms (visible, hidden, editable, selected, focused, enabled, hittable), and || fallback chains are highlighted inside strings, completed while you type a selector positional (role words after role=), and validated: unknown keys (button=Save → "try role=button"), empty values, empty || segments, bare words, unterminated quotes; label="Sign in" written without outer quotes (or with unescaped inner quotes) gets a quick fix to the form agent-device's tokenizer accepts

Running

• Run Output panel in the bottom panel container — opens to a workspace-wide .ad file picker; click any file to run
• Per-step UI as steps execute live: pending circle → spinner → green ✓ / red ✗ / muted skipped, with live duration counters
• Click any step row (passed/failed/running) to expand stdout, stderr, or the error block; copy buttons on every output block
• Stop button kills the in-flight subprocess immediately (forwards AbortSignal to the spawned agent-device)
• CodeLenses above each action line: ▶ Run (just that line) and ▶ Run up to here
• Native gutter test icons — every action line is a child TestItem with a range, so the editor gutter shows pass/fail icons after each run
• Test Explorer integration — every .ad file appears as a TestItem; runs from any entry point (panel, CodeLens, palette, native test gutter) all reflect the same state in the Testing view

Templates

• + New opens a QuickPick with 14 starter templates written against agent-device 0.21: empty file, iOS / Android Settings smoke, login flow, assert & wait cheat sheet, search & assert, scroll & discover, gestures (post-0.20 forms), visual baseline with diff screenshot, React Native (Metro), macOS desktop app, Linux desktop app, Android TV remote navigation. Templates use selectors (label=, id=, role=, ||), --settle, and is / wait absent / wait text assertions

Devices

• Devices view lists every iOS simulator and Android AVD, grouped by platform, booted entries first
• Boot / Shut down inline icons on hover, also in the right-click menu and Command Palette
• iOS uses xcrun simctl directly; Android uses emulator -avd + adb emu kill for reliable per-device control regardless of the daemon's session lock

Reports

• Every run writes a self-contained HTML report to <workspace>/.agent-device-reports/<iso-timestamp>/
• Sticky toolbar with search (/ to focus), status filter pills (All / Passed / Failed / Skipped with counts), Expand all / Collapse all
• Per-step Copy command + Copy stdout/stderr buttons; light/dark mode auto-detected; pure HTML/CSS/JS, no external assets — share by zipping the run folder

Requirements

• VS Code 1.101 or newer (extension host on Node 22.12+, which the bundled agent-device 0.21 CLI requires). Older editors can still use the extension by pointing agentDevice.cliPath at an agent-device install that runs on a newer Node.

Install (development)

npm install
npm run watch

Then press F5 in VS Code to launch the Extension Development Host. Open any folder containing .ad files and click the Agent Device tab in the bottom panel.

Install (packaged)

npm run package    # produces agent-device-devtools-<version>.vsix
code --install-extension agent-device-devtools-<version>.vsix

Settings

Open via the gear icon in either Agent Device view title, the Command Palette (Agent Device: Open Settings), or VS Code's settings UI filtered to agentDevice.

Setting	Default	Purpose
agentDevice.cliPath	bundled	Override path to the agent-device binary. Useful when developing against a local checkout.
agentDevice.session	vscode	Daemon session name used for replay runs.
agentDevice.androidSdkPath	$ANDROID_HOME	Override the Android SDK location used to find adb and emulator.
agentDevice.report.enabled	true	Generate HTML reports under .agent-device-reports/.
agentDevice.notifications.enabled	true	Show success / failure popups (status bar pill always shows).

User-level settings apply globally; workspace-level settings override per project — both surfaces are reachable from the gear icon.

Architecture

src/
  extension.ts                — activation; wires everything
  data/                       — static catalogs (commands, templates, platforms, variables)
  diagnostics/                — platform-value validator
  panels/                     — RunOutputPanel (webview, list + run views)
  providers/                  — completion, hover, codelens
  reports/                    — HtmlReportWriter + reportTemplate
  runners/                    — ReplayRunner (event emitter), CliRunner, scriptParser
  services/                   — AdFileIndex, DeviceCatalog, AgentDeviceConfig
  testing/                    — AgentDeviceTestController (TestRun mirroring)
  views/                      — DeviceTreeProvider
  util/                       — duration / pluralize helpers
media/
  agent-device.svg            — activity bar icon
  runOutput.css               — webview styles (loaded via webview.asWebviewUri)
syntaxes/
  agent-device.tmLanguage.json
examples/
  demo.ad

The runner spawns the agent-device CLI per step (so cancellation kills the in-flight subprocess immediately), parses .ad itself for variable interpolation and step-by-step events, and emits a typed event stream that every UI surface consumes.

Releases

See CHANGELOG.md. Publishing is documented in PUBLISHING.md.

License

MIT.