fsq-agent 0.1.5

Evidence-first AI UI automation you can inspect, replay, and verify.

Quickstart · 中文 · Detailed guide · CLI · Contributing

FSQ turns UI goals into observable Runs with screenshots, UI snapshots, events, and reports. Reviewed YAML Cases replay deterministically through Playwright, uiautomator2, pywinauto, or Appium while the local Control Plane keeps execution and evidence inspectable.

Recommended first run

Prerequisites are Python 3.11+ and an installed supported Chromium-family browser (the commands below use Chrome). Install or upgrade fsq-agent 0.1.5, create and open an empty directory, and initialize Web plus the package-owned, host-neutral Skill:

python -m pip install --upgrade fsq-agent
mkdir fsq-web-demo
cd fsq-web-demo
fsq init --platform web --browser-channel chrome --agent skill

This empty directory is the exact registered Workspace root. If you initialize from a non-empty directory instead, FSQ creates a child Workspace; use the root reported by init. Workspace commands never search parent directories.

Reload the compatible Coding Agent's project resources or start a new agent session, then paste this post-reload self-check prompt:

Use the installed FSQ Skill to run its bundled provider-free Web Strict self-check from the exact registered Workspace root <ABSOLUTE_WORKSPACE_ROOT>. Run it at most once. Return the authoritative status, exact persistent Run ID, and relative Control Plane route. Do not initialize, configure, edit a Case, retry, or start the Control Plane.

The agent should run Doctor, statically check the bundled Case, execute it once, read that exact Run, and return a route shaped like /#runs?workspace=...&platform=web&run=.... Start the UI yourself and open that relative route:

fsq ui

The Skill never starts the Control Plane. If no verified Run ID is returned, the result is unknown: do not retry and do not construct a route.

Copy-paste installer prompt for a Coding Agent

Use this only to install the integration. It is not the self-check prompt above.

Check that Python 3.11 or newer is available. Run fsq init --help and verify that --agent skill is supported. If fsq is missing, older than fsq-agent 0.1.5, or lacks that capability, ask my permission before running python -m pip install --upgrade fsq-agent; do not install anything without approval. From the exact project directory, run fsq init --platform web --browser-channel chrome --agent skill. Do not hand-create or modify any Skill or Case file, do not configure or change a Provider or secret, and do not run a Case. Report the exact Workspace root and installed Skill path, then remind me to reload project resources or start a new agent session before using the separate post-reload self-check prompt.

The official CLI may initialize a Workspace and install the Skill. The installed Skill itself may not initialize or configure anything.

Skill scope and failure transitions

One fsq-agent distribution owns .agents/skills/fsq/SKILL.md and its bundled provider-free Web Strict Case. Compatible GitHub Copilot and Codex clients discover that same .agents/skills/fsq/ location; there is no separate host-specific Skill distribution.

The Skill is intentionally limited to:

• read-only fsq doctor;
• read-only fsq case format ... --check --json;
• one fsq case test execution;
• fsq runs show for the exact returned Run ID (and optionally bounded exact-Run logs);
• an exact status/Run/relative-Control-Plane handoff.

It does not initialize/configure FSQ, handle Providers or secrets, edit/copy Cases, retry, operate browser UI, run Explore/suggestions/AI assertions, or start/call the Control Plane.

The older Codex TOML/managed-AGENTS.md integration remains an advanced compatibility path through fsq init --agent codex. Do not install both integrations for the first self-check.

Continue after the self-check

Strict replay is provider-free unless an authored Case contains an AI assertion. AI Explore (fsq case create), AI assertions, and post-run suggestions may require a configured Provider.

# AI exploration: execute a goal and produce a reviewable Run-local Case.
fsq case create --platform web \
  --goal "Open https://example.com and verify the Example Domain heading is visible."

# Review and format-check the returned Case before deterministic replay.
fsq case format cases/web/YOUR_CASE.fsq.yaml --check
fsq case test --platform web cases/web/YOUR_CASE.fsq.yaml

# Optional AI analysis executes the source Case once, then analyzes saved facts.
fsq case test --platform web --suggest cases/web/YOUR_CASE.fsq.yaml
fsq runs list --platform web
fsq runs show RUN_ID --open

The existing examples/web/example-domain.fsq.yaml is the recorded TodoMVC example despite its historical filename. It remains available for advanced/historical use, but is no longer the recommended first run.

Supported Providers are OpenAI, Azure OpenAI, DeepSeek, Google Gemini, Kimi (China or Global), and GitHub Copilot. Configuration is user-level under ~/.fsq; see Getting started for model, region, credential, and fallback details.

fsq providers configure github_copilot
fsq providers status

Platforms and local evidence

Run evidence lives under <workspace>/.fsq/runs/<platform>/<run-id>/. Review it before sharing; it can contain visible application data. Do not commit .fsq, credentials, reports, screenshots, or private target data.

See FSQ in action

https://github.com/user-attachments/assets/aa9d0a12-2f93-4894-8349-52a013424939

Watch the full demo on YouTube.

Documentation

• Getting started
• 中文快速开始
• CLI reference
• FSQ Case format
• Platform prerequisites
• Support and stability
• Codex advanced compatibility

License

MIT — Copyright (c) Microsoft Corporation.