calvana/.pi/skills/bowser.md

name, description, allowed-tools

name	description	allowed-tools
bowser	Headless browser automation using Playwright CLI. Use when you need headless browsing, parallel browser sessions, UI testing, screenshots, web scraping, or browser automation that can run in the background. Keywords - playwright, headless, browser, test, screenshot, scrape, parallel.	Bash

Playwright Bowser

Purpose

Automate browsers using playwright-cli (via @playwright/cli) — a token-efficient CLI for Playwright. Runs headless by default, supports parallel sessions via named sessions (-s=), and doesn't load tool schemas into context.

Prerequisites

Ensure the package is installed in the project:

bun add -d @playwright/cli
bunx playwright install chromium

Key Details

• Headless by default — pass --headed to open to see the browser
• Parallel sessions — use -s=<name> to run multiple independent browser instances
• Persistent profiles — cookies and storage state preserved between calls
• Token-efficient — CLI-based, no accessibility trees or tool schemas in context
• Vision mode (opt-in) — set PLAYWRIGHT_MCP_CAPS=vision to receive screenshots as image responses in context instead of just saving to disk

Sessions

Always use a named session. Derive a short, descriptive kebab-case name from the user's prompt. This gives each task a persistent browser profile (cookies, localStorage, history) that accumulates across calls.

# Derive session name from prompt context:
# "test the checkout flow on mystore.com" → -s=mystore-checkout
# "scrape pricing from competitor.com"    → -s=competitor-pricing
# "UI test the login page"               → -s=login-ui-test

bunx playwright-cli -s=mystore-checkout open https://mystore.com --persistent
bunx playwright-cli -s=mystore-checkout snapshot
bunx playwright-cli -s=mystore-checkout click e12

Managing sessions:

bunx playwright-cli list                                     # list all sessions
bunx playwright-cli close-all                                # close all sessions
bunx playwright-cli -s=<name> close                          # close specific session
bunx playwright-cli -s=<name> delete-data                    # wipe session profile

Quick Reference

Core:       open [url], goto <url>, click <ref>, fill <ref> <text>, type <text>, snapshot, screenshot [ref], close
Navigate:   go-back, go-forward, reload
Keyboard:   press <key>, keydown <key>, keyup <key>
Mouse:      mousemove <x> <y>, mousedown, mouseup, mousewheel <dx> <dy>
Tabs:       tab-list, tab-new [url], tab-close [index], tab-select <index>
Save:       screenshot [ref], pdf, screenshot --filename=f
Storage:    state-save, state-load, cookie-*, localstorage-*, sessionstorage-*
Network:    route <pattern>, route-list, unroute, network
DevTools:   console, run-code <code>, tracing-start/stop, video-start/stop
Sessions:   -s=<name> <cmd>, list, close-all, kill-all
Config:     open --headed, open --browser=chrome, resize <w> <h>

Workflow

1. Derive a session name from the user's prompt and open with --persistent to preserve cookies/state. Always set the viewport via env var at launch:

PLAYWRIGHT_MCP_VIEWPORT_SIZE=1440x900 bunx playwright-cli -s=<session-name> open <url> --persistent
# or headed:
PLAYWRIGHT_MCP_VIEWPORT_SIZE=1440x900 bunx playwright-cli -s=<session-name> open <url> --persistent --headed
# or with vision (screenshots returned as image responses in context):
PLAYWRIGHT_MCP_VIEWPORT_SIZE=1440x900 PLAYWRIGHT_MCP_CAPS=vision bunx playwright-cli -s=<session-name> open <url> --persistent

3. Get element references via snapshot:

bunx playwright-cli snapshot

4. Interact using refs from snapshot:

bunx playwright-cli click <ref>
bunx playwright-cli fill <ref> "text"
bunx playwright-cli type "text"
bunx playwright-cli press Enter

5. Capture results:

bunx playwright-cli screenshot
bunx playwright-cli screenshot --filename=output.png

6. Always close the session when done. This is not optional — close the named session after finishing your task:

bunx playwright-cli -s=<session-name> close

Configuration

If a playwright-cli.json exists in the working directory, use it automatically. If the user provides a path to a config file, use --config path/to/config.json. Otherwise, skip configuration — the env var and CLI defaults are sufficient.

{
  "browser": {
    "browserName": "chromium",
    "launchOptions": { "headless": true },
    "contextOptions": { "viewport": { "width": 1440, "height": 900 } }
  },
  "outputDir": "./screenshots"
}

Full Help

Run bunx playwright-cli --help or bunx playwright-cli --help <command> for detailed command usage.