# JigRig

Drives Windows desktop apps inside an isolated Windows Sandbox, so UI automation can run while
you keep using the machine. Synthetic input lands in the guest; your mouse, keyboard, clipboard
and windows are never touched.

## What got installed

```
%USERPROFILE%\JigRig\
  bin\mcp\JigRig.Mcp.exe        the MCP server Claude Code talks to, and --doctor
  bin\doctor\JigRig.Doctor.exe  the same checks with buttons
  bin\testapp\                  a deterministic app to smoke-test against
  share\                        mapped into the guest as C:\JigRig
    jig\                        Jig, which drives the guest desktop
    agent\                      the guest agent
  jigrig.json                   configuration (created on demand; yours)
  reports\ deploys\ logs\       state (yours)
```

Re-running the installer replaces `bin`, `share\jig` and `share\agent`. Everything else is left
alone.

## Do this first

```
%USERPROFILE%\JigRig\bin\mcp\JigRig.Mcp.exe --doctor
```

Twenty-two checks covering this machine and the staged payload, each reporting the value it
actually observed and, where one exists, how to fix it. `--fix` applies the automatic ones.
`bin\doctor\JigRig.Doctor.exe` is the same thing with clickable fixes and a Start button.

It can tell you the rig will not run here, and that is a useful answer. Windows Sandbox needs
Windows Pro, Enterprise or Education, hardware virtualization, and the `Containers-DisposableClientVM`
optional feature. On a managed machine, group policy can block mapped folders, writes to them, or
networking; any of those and the rig cannot work. The doctor names which one rather than failing
mysteriously later.

## Using it from Claude Code

The installer registers the MCP server as `jigrig` at user scope. The lifecycle:

```
rig_doctor                      is this machine capable, and what is wrong
rig_up                          start the sandbox, wait for the guest agent
rig_deploy  name=X hostFolder=  push a published app into the guest
rig_launch  app=X               start it and attach
vm_*                            drive it: the ordinary Jig tools, running in the guest
rig_logs    app=X               boot log, agent log, Jig log, app logs, event log, crash dumps
rig_reset                       pristine desktop again
```

`vm_*` is the full Jig tool surface forwarded into the guest. Prefer the UIA verbs: `vm_click`,
`vm_type`, `vm_read`, `vm_set_toggle`, `vm_select`, `vm_invoke_menu`. When `rig_doctor` reports
`guest.dpi` as anything other than 96, the coordinate verbs (`vm_real_click`, `vm_teleport_click`,
`vm_pixel_click`, `vm_drag`, `vm_hover`) will silently do nothing: the guest inherits the host's
display scaling, and UIA reports logical coordinates while synthetic input consumes physical ones.

## Things worth knowing

- **The guest keeps nothing.** `rig_reset` and `rig_down` discard everything in it, deployed apps
  included. Redeploy after a reset; `rig_status` lists what it thinks is there.
- **One sandbox at a time.** Windows allows exactly one, so another tool using it will block the
  rig and vice versa.
- **The viewer window matters.** A headless sandbox has no user session at all, which means no
  desktop for Jig to drive. The rig attaches a viewer as part of starting up; closing that window
  takes the guest down with it.
- **A sandbox has no inbox apps.** There is no Notepad and no Calculator in there, which is what
  `bin\testapp` is for.

## Hyper-V instead of Windows Sandbox

If the doctor says Windows Sandbox cannot work here (the viewer keeps crashing, the Store app is
blocked, policy forbids mapped folders or networking) the rig can run in a small Hyper-V VM
instead. Put `"provider": "hyperv"` in `%USERPROFILE%\JigRig\jigrig.json`, drop a Windows 11 ISO
in `C:\ISOs` (or set `hyperv.isoPath`), run `rig_provision check=true` (a preflight that needs no
UAC and changes nothing), and then `rig_provision` once. It raises one UAC prompt,
builds the VM from the ISO without ever showing Windows Setup (ten to twenty minutes), and adds
you to the local Hyper-V Administrators group; sign out and back in after it, then `rig_up` as
before. The guest logs itself in, so no viewer window is involved, and `rig_reset` restores a
checkpoint in seconds. Everything else (`rig_deploy`, `rig_launch`, `vm_*`, `rig_logs`) is the
same. Needs Windows Pro, Enterprise or Education with Hyper-V enabled; `rig_doctor` checks that
too (`host.hyperv*`).

## Updating

Re-run the install one-liner. It replaces the binaries and leaves your configuration, deploys and
reports in place. A part that is held open (a running guest keeps `share\jig` busy) is kept as it
was and named in a warning; stop the guest and re-run to finish.