playwright-axi

Agent-ergonomic browser automation over the Playwright engine. playwright-axi wraps the playwright npm package's embedded agent CLI (playwright cli) with an AXI-compliant surface: TOON output, combined operations, inline filtered snapshots, structured errors, and contextual next steps — so coding agents drive a real browser with the fewest turns and tokens possible.

Why

Microsoft's playwright-cli is already agent-friendly, but its replies are optimized for humans reading a terminal: page state as markdown headers, snapshots as file links, plain-text listings, and inconsistent JSON envelopes. playwright-axi keeps the engine (daemon, sessions, ref-based snapshots, Chromium/Firefox/WebKit) and rebuilds the agent-facing surface on AXI principles:

AXI principle	playwright-axi behavior
Token-efficient output	Compact TOON text by default; --json on demand
Combined operations	Every action returns action + page URL/title + inline snapshot in one call
Query filtering	--query "login submit" filters any snapshot to matching lines
Content truncation	Snapshots cap at 120 lines with a size hint; --full escape hatch
Pre-computed aggregates	totals: {messages: 2, errors: 1, warnings: 0} inline in console output
Definitive empty states	sessions: 0, matches: 0, requests: 0 — never blank output
Structured errors & exit codes	{error, code, help[]} on stdout; 0 success, 2 usage, 1 runtime
Content first	Bare playwright-axi shows live session state, not help text
Contextual disclosure	help[] next-step lines after outputs
Consistent help	--help per command, generated from the command registry

Refs ([ref=eN]) work exactly like playwright-cli's: they address elements from the most recent snapshot. When a ref goes stale, the CLI fails loudly with a structured STALE_REF error and the remediation command, instead of letting the engine's raw error scroll by.

Install

As an agent skill (recommended)

npx -y skills@latest add brycehamrick/playwright-axi --skill playwright-axi -g

The skill teaches your agent to run the CLI through npx -y playwright-axi@latest, so nothing needs to be pre-installed.

As a global CLI

npm install -g playwright-axi
playwright-axi open https://example.com

The playwright npm package is a direct dependency and downloads Chromium, Firefox, and WebKit on install. For a lean install (Chromium later, on demand):

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm install -g playwright-axi
playwright-axi install chromium

Ambient context (optional)

playwright-axi setup hooks

installs a SessionStart hook for Claude Code, Codex, and OpenCode that surfaces the live browser-session dashboard at the start of every agent session. Restart your agent afterward.

Quick start

$ playwright-axi open https://example.com
page: {url: https://example.com/, title: "Example Domain"}
snapshot_file: .playwright-cli/page-2026-09-17T19-02-19-850Z.yml
snapshot:
  - generic [ref=e2]:
    - heading "Example Domain" [level=1] [ref=e3]
    - paragraph [ref=e4]: This domain is for use in documentation examples...
    - paragraph [ref=e5]:
      - link "Learn more" [ref=e6] [cursor=pointer]:
        - /url: https://iana.org/domains/example
help[2]:
  Run `playwright-axi find <text>` to search the page
  Run `playwright-axi click <ref>` using a [ref=eN] from the snapshot

$ playwright-axi click e6 --query "example domains"
page: {url: https://www.iana.org/help/example-domains, title: "Example Domains"}
matches: 3 of 133 lines
snapshot:
  ...

One command navigates, clicks, waits, captures, filters, and suggests the next step. Compare that to the navigate → snapshot → grep → act → snapshot cycle of unmodified CLIs.

Commands

playwright-axi --help prints the full grouped reference; playwright-axi <command> --help shows exact arguments and flags. The surface mirrors playwright-cli for zero translation cost:

• Session — open, attach, detach, close, sessions, close-all, kill-all, delete-data (--confirm), install, show
• Navigation — goto, go-back, go-forward, reload
• Snapshot & inspection — snapshot, find, eval, generate-locator, highlight
• Interaction — click, dblclick, fill (--submit), type, press, keydown/keyup, hover, select, check/uncheck, drag, drop, upload, dialog-accept/dialog-dismiss, resize
• Mouse (coordinates) — mousemove, mousedown, mouseup, mousewheel
• Tabs — tab-list, tab-new, tab-close, tab-select
• Capture — screenshot, pdf (Chromium), state-save, state-load
• Cookies & storage — cookie-*, localstorage-*, sessionstorage-*
• Console & network — console, requests, request, request-headers/request-body, response-headers/response-body, route, route-list, unroute, network-state-set
• DevTools — run-code, recording-*, tracing-*, video-*, pause-at, resume, step-over
• WebMCP (experimental) — webmcp-list, webmcp-call

Universal flags on every command: --session <name> (-s), --query <text>, --full, --json, --timeout <ms>. Unknown flags fail loudly with the valid flag list and exit 2.

Sessions

Browsers are named sessions. Pass --session <name> (or set PLAYWRIGHT_AXI_SESSION) to isolate work — for example one session per app under test. playwright-axi sessions lists live sessions with their current page. Sessions default to headless Chromium; open --browser firefox, --headed, --mobile, --device "iPhone 15", and --persistent change that. Headless sessions shut down after an hour idle; run open again.

Engine notes

• The engine is the playwright npm package's cli subcommand — the same implementation Microsoft ships as @playwright/cli. This package pins stable playwright releases.
• Snapshots, screenshots, PDFs, and storage states are written to ./.playwright-cli/ next to wherever you invoke the CLI, matching the engine's convention.
• playwright-axi install [browser] proxies playwright install (use --with-deps on Linux for system dependencies).

Safety & privacy

• No credentials are read, stored, or logged. The engine child inherits your environment plus NO_UPDATE_NOTIFIER=1; nothing else is injected and no secrets appear in output.
• No command prompts for interactive input.
• Browser actions (navigate, click, fill) are ungated by design — they are agent-driven and page-scoped, matching the reference browser-automation AXI. The only persisted-data mutation (delete-data) requires --confirm.

Exit codes

Code	Meaning
0	success
2	usage error — unknown flag, missing/invalid argument, missing --confirm
1	runtime error — engine failure, NO_SESSION, STALE_REF, timeout

Errors are structured (error, code, help[]) and written to stdout.

Development

npm install          # browsers can be skipped: PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
npm run build
npm test             # unit tests; the engine is mocked, no browser needed
npm run typecheck

The command registry (src/registry.ts) is the single source of truth for the CLI surface; per-command flag specs mirror the engine's own --help output. See AGENTS.md for conventions.

Contributing to the AXI catalog

This AXI is listed in the axi.md catalog. The exact catalog.yaml entry and contribution workflow live in docs/catalog-entry.md.

License

MIT