@arqade/agent

MCP server that lets a Claude Code session drive and check your web or Electron app through Playwright, and audit the project's Arqade setup.

Part of Arqade — your AI QA partner for Electron and web apps.

0.3.0 moved arqade onto the Playwright MCP engine. The browser tools are Playwright MCP's (browser_click, browser_snapshot, …), and the 0.2 tools (screenshot, click, type, …) are gone. See the migration notes in the CHANGELOG.

MCP server

Add the server to your Claude Code config (.mcp.json in your project root):

{
  "mcpServers": {
    "arqade": {
      "command": "npx",
      "args": ["-y", "-p", "@arqade/[email protected]", "arqade-mcp"]
    }
  }
}

A Claude Code session sees each tool as mcp__arqade__<name>. The default (worker) profile serves 27 tools; ARQADE_PROFILE=dev adds 27 more for code, network routing, storage, tracing and video.

arqade's own

• connect — url launches your Chrome, else Edge, else Playwright's headless shell, and opens the URL; cdp attaches to a running Chromium or Electron app (for example http://localhost:9222). Optional viewport, slot and log_sources. The result shows what is on screen.
• disconnect — closes a launched browser, or detaches from a CDP app and leaves it running.
• act — 1–20 browser steps in one call, all checked first. It stops at the first failure and ends with one on-screen state.
• audit — inspects the project's .arqade/ files.

Look: browser_snapshot, browser_find, browser_take_screenshot. Act: browser_click, browser_type, browser_fill_form, browser_select_option, browser_hover, browser_press_key, browser_drag, browser_file_upload, browser_handle_dialog. Move: browser_navigate, browser_navigate_back, browser_tabs, browser_wait_for, browser_reload. Check: browser_console_messages, browser_network_requests, browser_verify_text_visible, browser_verify_element_visible, browser_verify_value, browser_evaluate.

A target is a ref from a snapshot (e12) or one unique selector ([data-testid="save"]). Act and Move results report what changed (### Changes: URL, title, page errors, failed requests, dialogs, tabs) and what is now on screen (### On screen). A missing target lists its near matches.

Alerts from watched log files (connect's log_sources, or .arqade/log-sources.json) appear as a short ### Log alerts section on the next result, at most once a minute each.

Each connect writes one JSONL line per tool call (and per act step) to <project_dir>/.arqade/logs/session-<timestamp>.log.

Browsers

connect with a url launches Google Chrome, else Microsoft Edge, else Playwright's headless shell (Chromium, revision 1248). When none of them launches, it installs the headless shell first (about 100 MiB), so that connect can take a while; it is bounded at 300 s. When no browser can be launched at all, connect returns browser missing, with each attempt's reason and the fix. cdp mode launches nothing.

To check for a browser, or install the headless shell, ahead of time, run the package's entry (dist/mcp-entry.js, the arqade-mcp bin) with install-browser:

npx -y -p @arqade/[email protected] arqade-mcp install-browser --check   # never installs
npx -y -p @arqade/[email protected] arqade-mcp install-browser           # installs the headless shell when no browser launches

It starts no MCP server. It prints one JSON line and exits 0 on ready or installed, 1 otherwise:

{"status":"ready|installed|missing|failed","browser":"chrome|msedge|chromium-headless-shell","path":"…","error":"…"}

A host whose Claude sessions run in a sandbox that cannot write the browsers folder runs node <entry> install-browser from its own process; inside the sandbox, the install fails with browser install not permitted here. The full contract is in docs/superpowers/contracts/install-browser.md.

ARQADE_BROWSERS_PATH sets the folder the headless shell is looked for in and installed into. It must be an absolute path (a relative one, ~/… included, is refused); give connect's server and install-browser the same value. Unset, Playwright's own default is used (~/Library/Caches/ms-playwright on macOS).

Onboarding a new project

1. Audit first. From your project root, run:

   npx -y -p @arqade/agent arqade audit

   You'll see a table of what's set up, what's missing, and what's not applicable. The ready_to_connect line at the bottom is false only when the audit finds an invalid row, such as malformed JSON.

2. Generate stubs for the elements you want:

   npx -y -p @arqade/agent arqade audit --suggest lifecycle > .arqade/lifecycle.json
   npx -y -p @arqade/agent arqade audit --suggest backend > .arqade/backend.json

   Remove the // … comments and fill in the <FILL> placeholders. lifecycle.json holds dev_command and ready_url (or ready_port). Your host's launcher reads them to start the app; arqade only validates them.

3. Skip what doesn't apply. Run npx -y -p @arqade/agent arqade audit --suggest audit-skip > .arqade/audit-skip.json, then list the elements your app doesn't support. Those rows render as not-applicable rather than missing.

4. Re-audit until every row you care about is setup.

Claude sessions can run the same audit with the audit tool: audit({ project_dir: "." }).

arqade audit

arqade audit [project_dir] [options]

Arguments:
  project_dir              Path to audit (default: cwd)

Options:
  --json                   Output JSON to stdout (no markdown table)
  --strict                 Treat incomplete/missing as failure (exit 2 instead of 1)
  --skip <list>            Ad-hoc skip list (comma-separated element names),
                           OR'd with .arqade/audit-skip.json contents
  --capability <list>      Show only rows matching one of the named capabilities
  --suggest <element>      Print a stub template for <element> to stdout, then exit

Exit codes:

• 0 — all rows setup or not-applicable
• 1 — at least one row incomplete or missing (without --strict)
• 2 — at least one row invalid, OR --strict and any non-setup
• 3 — audit itself failed (project_dir not found etc.)
• 4 — unknown flag / bad argument

Requirements

• Node.js 20+
• A web app served on a URL, or an Electron or Chromium app started with a remote-debugging port
• Google Chrome or Microsoft Edge, or Playwright's headless shell (see above)

License

MIT — see LICENSE.

See also

• Root README — what Arqade is, who it's for.
• CHANGELOG — release notes and the 0.3.0 migration.

Real-world adopter

Tempo is the canonical adopter: its Claude Code sessions use arqade-mcp to test the apps they build.