Install the desktest CLI by running `curl -fsSL https://raw.githubusercontent.com/Edison-Watch/desktest/master/install.sh | sh`. Then copy `skills/desktest-skill.md` from the desktest repo (https://raw.githubusercontent.com/Edison-Watch/desktest/master/skills/desktest-skill.md) to `~/.claude/skills/desktest/SKILL.md` so you have context on how to use it.

# Or build from source
git clone https://github.com/Edison-Watch/desktest.git
cd desktest
make install_cli

desktest [OPTIONS] <COMMAND>

Commands:
  run           Run a single test from a task JSON file (supports --replay for deterministic mode)
  suite         Run all *.json task files in a directory
  interactive   Start container and pause for debugging
  attach        Attach to an existing running container (supports --replay)
  validate      Check task JSON against schema without running
  codify        Convert trajectory to deterministic Python replay script
  review        Generate interactive HTML trajectory viewer
  logs          View trajectory logs in the terminal (supports --steps N, N-M, or N,M,X-Y)
  monitor       Start a persistent monitor server for multi-phase runs
  init-macos    Prepare a macOS golden image for Tart VM testing
  doctor        Check that all prerequisites are installed and configured
  update        Update desktest to the latest release from GitHub

Options:
  --config <FILE>            Config JSON file (optional; API key can come from env vars)
  --output <DIR>             Output directory for results (default: ./test-results/)
  --debug                    Enable debug logging
  --verbose                  Include full LLM responses in trajectory logs
  --record                   Enable video recording
  --monitor                  Enable live monitoring web dashboard
  --monitor-port <PORT>      Port for the monitoring dashboard (default: 7860)
  --monitor-bind-addr <ADDR> Bind address for dashboard (default: 127.0.0.1, use 0.0.0.0 for remote)
  --resolution <WxH>         Display resolution (e.g., 1280x720, 1920x1080, or preset: 720p, 1080p)
  --artifacts-dir <DIR>      Directory for trajectory logs, screenshots, and a11y snapshots
  --no-artifacts             Skip artifact collection entirely
  --artifacts-timeout <SECS> Timeout for artifact collection (default: 120, 0 = no limit)
  --artifacts-exclude <GLOB> Glob patterns to exclude from artifact collection (repeatable)
  --qa                       Enable QA mode: agent reports app bugs during testing
  --with-bash                Allow the agent to run bash commands inside the container (disabled by default)
  --no-network               Disable outbound network from the container (Docker network mode "none")
  --provider <PROVIDER>      LLM provider: anthropic, openai, openrouter, cerebras, gemini, claude-cli, codex-cli, custom
  --model <MODEL>            LLM model name (overrides config file)
  --api-key <KEY>            API key for the LLM provider (prefer env vars to avoid shell history exposure)
  --llm-max-retries <N>      Max retry attempts for retryable LLM API failures

Developer writes task.json
        │
        ▼
   ┌──────────────┐
   │ desktest CLI  │  validate / run / suite / interactive
   └────┬─────────┘
        │
        ├─── Linux ────────────────────┐     ├─── macOS ────────────────────┐
        │  Docker Container            │     │  Tart VM (or native host)    │
        │  Xvfb + XFCE + x11vnc        │     │  Native macOS desktop        │
        │  PyAutoGUI (X11)             │     │  PyAutoGUI (Quartz)          │
        │  pyatspi (AT-SPI2)           │     │  a11y-helper (AXUIElement)   │
        │  scrot (screenshot)          │     │  screencapture (screenshot)  │
        └──────────┬───────────────────┘     └──────────┬───────────────────┘
                   │ screenshot + a11y tree             │
                   └──────────────┬─────────────────────┘
                                  ▼
                     ┌──────────────────┐
                     │  LLM Agent Loop  │  observe → think → act → repeat
                     │  (PyAutoGUI code)│
                     └────────┬─────────┘
                              │
                              ▼
                     ┌──────────────────┐
                     │  Evaluator       │  programmatic checks / LLM judge / hybrid
                     └────────┬─────────┘
                              │
                              ▼
                     results.json + recording.mp4 + trajectory.jsonl

test-results/
  results.json                # Structured test results (always)

desktest_artifacts/
  recording.mp4               # Video of the test session (with --record)
  trajectory.jsonl            # Step-by-step agent log (always)
  agent_conversation.json     # Full LLM conversation (always)
  step_001.png                # Screenshot per step (always)
  step_001_a11y.txt           # Accessibility tree per step (always)
  bugs/                       # Bug reports (with --qa)
    BUG-001.md                # Individual bug report (with --qa)