name: win32-drive os: win32 description: "Use for inspecting, driving, or debugging Windows desktop GUIs, including cursor and pointer issues." compatibility: "Windows PowerShell 5.1 (powershell.exe), 64-bit recommended"
Win32 Drive
Resolve scripts/win32-drive.ps1 against this skill's directory and pass that absolute path; never rely on the current directory.
powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -WindowStyle Hidden -File <skill-dir>/scripts/win32-drive.ps1 <cmd> [opts]
All commands emit one JSON object with ok, cmd, and elapsedMs; failures add code and hint and exit nonzero. help prints the full command and option catalog, so read it instead of guessing flags.
Work in this order
- Observe —
list,shot,uia,pixel,focus,idle,clipboard. Free, invisible, never disturbs the human. - Act in the background —
uia-invoke,uia-set,window,clipboard -Set,theme. These change the app through accessibility or messages: no activation, no pointer, no keystrokes. The human keeps typing in another window. - Take over the machine —
click,type,key, or any-Focus auto. Last resort only.
Before anything in step 3: ask the human first and say what you will click or type. The human is usually working on this machine; a takeover steals the pointer and the foreground window. Never chain takeovers silently; ask once per task, not once per click.
If step 2 fails with no-pattern, that app has no usable accessibility action — report that to the human and ask for permission to use the pointer instead of just escalating.
Be fast
Process start costs about 1.4s and dwarfs every action, so batch whole interactions into one invocation:
# steps.json
[{"cmd":"uia-invoke","TitleContains":"Notepad","Name":"File"},
{"cmd":"wait","ms":250},
{"cmd":"uia-set","TitleContains":"Notepad","ClassName":"*EDIT*","Value":"hello"},
{"cmd":"shot","TitleContains":"Notepad","Out":"C:/temp/after.png"}]
... -File <skill-dir>/scripts/win32-drive.ps1 batch -File steps.json
- Steps use the same option names as the command line; flags are
true("Pointer": true). {"cmd":"wait","ms":300}pauses between steps; use it instead of separate invocations.- Execution stops at the first failing step (
failedAt, per-stepcode) unless-ContinueOnError. -Jsonalso works from Bash or Nushell, but PowerShell mangles embedded quotes: prefer-Fileor stdin.
Do not re-query what a result already contains:
listreturnscount,foreground,idleMs, and per windowz,focused,minimized; it accepts-Process/-TitleContains/-Hwndfilters.click/type/keyreturntarget,foreground,returnedTo.windowreturns the updated window rect.uia-invoke/uia-setreturn the matchedelementand whichpatternfired.- Errors return context:
candidatesforno-window,ambiguous-window,no-element,ambiguous-element;foreground,lockTimeoutMs,idleMsforfocus-denied.
The native layer is compiled once and cached in %LOCALAPPDATA%\win32-drive; help.nativeLoad reports cache, compiled, or loaded. A compiled result means the cache was cold, which also briefly spawns the C# compiler; steady state is cache.
Acting without stealing focus
Read the tree with uia, then address the element by -Name, -AutomationId, -ClassName, or -ControlType; string filters accept wildcards, -Index disambiguates, ambiguity reports candidates.
uia-invoke tries Invoke, Toggle, SelectionItem, ExpandCollapse, MSAA default action, then BM_CLICK. uia-set tries ValuePattern, then posts characters to the control and verifies the resulting text. Both report which path fired and leave the foreground window alone. They cannot hover, drag, or reach anything outside the accessibility tree; GPU-rendered apps often expose nothing.
Takeover contract
Pointer input requires the explicit -Pointer flag. click always needs it; type and key need it only for -Focus auto, whose fallback is a pointer click on the target caption.
Every takeover: wait for an input gap, then show a red border, a ring on the target point, and a banner naming the action and target window, counting down (-CountdownMs, default 1200). Any keyboard or mouse input during the countdown cancels the action with code takeover-aborted; that is the human vetoing you, so stop and ask again. -NoCountdown skips the countdown and belongs to tests, not to a desktop in use.
Focus modes: require (default, activation APIs only), auto (adds the caption click, needs -Pointer), skip (no focusing). Focusing happens after the guard, because Windows denies activation while the human is typing. Minimized targets fail; restore them first.
After acting, focus returns to the window the human was using (-Return restore, default; returnedTo reports the result). Pass -Return keep when the next step in the same batch needs the target focused.
-IdleMs n (default 800) and -TimeoutMs n (default 10000) tune the idle gate. overlay -Text "..." previews the banner without acting.
Coordinates
Screen pixels everywhere, except click -X/-Y with a window selector, which are relative to the window origin reported by list and shot. Without -X/-Y, a window click targets the center.
uia returns screen coordinates: convert with click -X (uia.x - shot.x) -Y (uia.y - shot.y), or click without a selector. shot -Hwnd returns exactly the list frame bounds, so image pixel (0,0) is screen pixel (x,y) in both printwindow and screen-crop modes. After shot, read the returned PNG path with the harness read tool.
Limits
No UAC secure desktop or lock screen; elevated apps need an elevated agent. GPU/fullscreen windows fall back to screen-crop, which captures whatever is on top. A hung foreground window (foreground.hung) cannot be displaced at all. Theme changes broadcast WM_SETTINGCHANGE to every window and have wedged apps here: set a theme once, never in a loop, and -Refresh full additionally perturbs per-user parameters. Never use AttachThreadInput for activation: it couples input queues and has hung the host terminal here.
Tests
npm test runs the existing PowerShell integration suite only on Windows with explicit consent: set WIN32_DRIVE_DESKTOP_TEST=I_UNDERSTAND_THIS_CONTROLS_MY_DESKTOP. Without both conditions, Node reports the test skipped with its reason; skip is not validation.
Prerequisites: Windows PowerShell 5.1 (powershell.exe), interactive Windows desktop, .NET WinForms/UI Automation; no npm dependencies. The suite creates and closes fixture windows, uses real pointer and keyboard input, briefly displays overlays, temporarily changes then restores clipboard, captures screenshots in %TEMP%, and may compile/cache a native helper under %LOCALAPPDATA%\win32-drive; it takes over mouse, keyboard, and clipboard for about a minute. Do not opt in while anyone is using the desktop. It does not write themes by default.
mise run win32-drive-test (from the dotfiles root) invokes the same suite and has the same desktop side effects. Theme writes need -IncludeTheme on a direct PowerShell invocation.