headspin-control · claude code plugin · v1.2.0

Drive real devices.
Find real bugs.

A HeadSpin device farm, driven from your terminal — lock a phone, record a session, crawl an app for defects, pull performance reports. Live-validated on 34 real devices. No mocks.

what it does

Six things, one plugin

DEVICES

Live device inventory

List every phone, tablet, TV in the farm — status, model, OS. 34 Android/iOS/Roku online.

CONTROL

Reserve & drive

Lock a device, open an Appium session, tap / swipe / type / launch apps in real time.

CAPTURE

Record sessions

Full lifecycle: lock → record → drive → stop → download the MP4, HAR, logs.

EXPLORE

Find app defects

Crawl the app and surface real UI / accessibility bugs from its live a11y tree.

WATERFALL

Performance reports

Pull HeadSpin's issue cards — page-load, frame rate, audio — plus network waterfalls.

REPORT

File bugs

Turn exploration findings into standardized, redacted bug reports with full evidence.

01

devices

See the whole farm.

One command, every device, real-time status.

/headspin:devices

terminal

/headspin:devices --platform android
# → hs_list_devices  (GET /v0/devices, Bearer auth)

  SAMSUNG SM-G991U   android 14   status 3 · ready
  GOOGLE  Pixel 6     android 12   status 3 · ready
  SAMSUNG SM-G973W   android 12   status 3 · ready
  ROKU    Streaming Stick+  15.2.4 status 3 · ready
  …
  34 devices online · 20 android · iOS · Roku

02

control

Reserve it. Drive it.

Lock a device, open a session, send real input.

connect

Open a session

/headspin:connect android locks the device and opens a real Appium wd/hub session against the target app — routed automatically for Android, iOS, or Roku.

drive

Send input

/headspin:control — screenshot, tap, swipe, keypress, launch. Backed by hs_adb_shell: input tap, input swipe, am start.

03

capture

Record a full session.

Lock → record → drive → stop → download — six real REST calls.

the capture lifecycle

/headspin:capture

01

Lock

Reserve the device so nothing else drives it.

hs_adb_lock

02

Record

Start a capture session — screen video begins.

hs_start_capture

03

Drive

Tap / swipe / launch the app under test.

hs_adb_shell

04

Stop

End the session; HeadSpin finalizes the MP4.

hs_stop_capture

05

Download

Pull the MP4, HAR, pcap, device logs.

hs_session_download

04

waterfall

What did the platform see?

HeadSpin's own performance analysis, surfaced as issue cards.

/headspin:waterfall · /headspin:sessions

Performance & network reports

hs_session_issues

Issue cards

Page-load, low frame rate, audio-too-quiet, and more — HeadSpin's Waterfall verdicts on the session.

hs_session_timeseries_info

Time series

Discover up to 31 device signals — memory, battery, network, video-quality MOS — then hs_session_timeseries_download pulls any series to CSV.

hs_session_download

Network waterfall

Full HAR of every request, plus pcap and TLS exceptions for gap analysis.

hs_session_video_metadata

Video + timestamps

MP4 metadata, capture start/stop marks, analysis-ready status polling.

05

explore

Find bugs in the app itself.

Crawl the app, read its accessibility tree, flag real UI defects.

/headspin:explore

Crawl → inspect → flag

Bounded BFS crawl — opens each screen of the app under test, one at a time.
Reads the live a11y tree — Appium page_source + a screenshot at every screen.
Runs defect predicates — package-scoped, subtree-aware, over the real tree.
Bundles evidence — the offending node, its bounds, the source XML, the screenshot.

defect predicates · a11y_defects.py

Four ways the app fails its users

A1

Crash / ANR dialog

A system "isn't responding" / "has stopped" dialog on top of the target app.

critical

A3

Unlabeled clickable

A control whose entire subtree has no text or content-desc — TalkBack can't announce it.

medium

A4

Unlabeled image control

A clickable ImageButton leaf with empty content-desc and no labelled child.

high

A5

Undersized touch target

An on-screen control below 48 dp — the Material / WCAG 2.5.8 minimum.

low

proven live · Pixel 6 · com.android.settings

What one crawl found

1

genuine defect

24.5dp

vs 48dp minimum

2

false positives caught

10

screens crawled

On the Security screen, the Dismiss (✕) button on the "Update this device" banner is 63×63 px ≈ 24.5 dp — half the Material minimum. Package-scoped, source-cited, screenshot-corroborated.

06

report

Turn findings into filed bugs.

Standardized reports, full evidence, tokens redacted.

/headspin:report

BUG-1.json

{
  "session_id": "59d2da99-…",
  "target_app": { "package": "com.android.settings",
                  "screen": "Security" },
  "defect": {
    "class": "A5_undersized_touch_target",
    "element": "banner_dismiss_btn",
    "bounds": "[922,1174][985,1237]",   # 63×63px = 24.5dp
    "evidence": { "source": "vg3-s7.xml",
                  "screenshot": "vg3-s7.png" }
  }
}

under the hood

20 live MCP tools

Area	Tools
Devices	`hs_list_devices` · `hs_idevice_info` · `hs_installer_list` · `hs_login_details`
Lock / drive	`hs_adb_lock` · `hs_adb_unlock` · `hs_adb_shell` · `hs_lock_device` · `hs_unlock_device`
Capture	`hs_start_capture` · `hs_stop_capture` · `hs_list_sessions`
Analysis	`hs_session_issues` · `hs_session_timeseries_info` · `hs_session_timeseries_download` · `hs_analysis_status`
Artifacts	`hs_session_download` · `hs_session_video_metadata` · `hs_session_timestamps` · `hs_session_tls_exceptions`

the verbs you type

10 slash commands

Command	What it does
`/headspin:setup`	Verify config & onboard the plugin
`/headspin:login`	Authenticate — mint an API token (env only)
`/headspin:devices`	List the live device roster
`/headspin:connect`	Lock a device & open a control session
`/headspin:control`	Drive it — tap, swipe, type, screenshot
`/headspin:capture`	Full lock → record → drive → stop → download
`/headspin:explore`	Crawl the app for real UI / a11y defects
`/headspin:report`	File standardized bug reports
`/headspin:sessions` · `:waterfall`	Pull performance reports & network waterfalls

get started